sqlite_web_vfs 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 285cd03d979c57d50cbe483330d345f16eaa4eefcdc7e3672c7d4d2717dc6dfd
+  data.tar.gz: 4111ca88772ffa0e35f6807fcadbd3905a058d9bffb8352c59a12c7feba01d30
+SHA512:
+  metadata.gz: 4b465bd199fd173480be78be31c866cfeedc8ec4bbb88225f56c73f51a70bc98fa14e2360fc5224f2151e633e6b58a2b01dc93e7a5c112b0b15079bcd6caf7aa
+  data.tar.gz: 1731b2b7c91d9606eafdf8ccdfcf959ef2dd08ddcf6e12dd0a0c24e4d1d70b32b1fe5eada7067f8ba5d6a73a04c7bf754928abf08275615a68c0736563b77a0c

data/LICENSE-3RD-PARTY.md

@@ -0,0 +1,32 @@
+This gem vendors C/C++ sources from mlin/sqlite_web_vfs.
+
+Upstream license (from mlin/sqlite_web_vfs/LICENSE):
+
+----------------------------------------
+Copyright (c) 2023-2024, Mike Lin
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+----------------------------------------
+

data/README.md

@@ -0,0 +1,118 @@
+# sqlite_web_vfs (Ruby gem)
+
+This gem builds and loads the HTTP VFS from mlin/sqlite_web_vfs as a Ruby native extension (no CMake), and exposes a small loader helper to use it from both `sqlite3` and `sqlite3-ffi`.
+
+Note: This gem includes code from mlin/sqlite_web_vfs, used under its original license.
+
+## Features
+- Wraps upstream C/C++ sources without modification (vendored in `ext/sqlite_web_vfs/upstream/`).
+- Builds with `mkmf` and auto-detects SQLite via `pkg-config` or flags.
+- macOS (Homebrew) and Amazon Linux 2023 supported.
+- Optional, opt-in bundled SQLite amalgamation: `WEBVFS_FORCE_BUNDLED=1`.
+- Loader works with both `sqlite3` and `sqlite3-ffi`.
+
+## Install
+- macOS (Homebrew): `brew install sqlite curl`
+- Amazon Linux 2023: `sudo dnf install sqlite-devel libcurl-devel`
+
+Then:
+
+```
+gem build sqlite_web_vfs.gemspec
+gem install ./sqlite_web_vfs-*.gem
+```
+
+If SQLite isn’t found, you can point to it:
+
+```
+gem install sqlite_web_vfs -- --with-sqlite3-dir=/usr/local/opt/sqlite
+```
+
+Advanced option: bundle SQLite amalgamation inside the extension (may not interoperate with other SQLite users in the same process):
+
+```
+WEBVFS_FORCE_BUNDLED=1 gem install sqlite_web_vfs
+```
+
+## Security
+Loading extensions can execute arbitrary native code. Only load trusted extensions from trusted locations and review your supply chain.
+
+## Runtime API examples
+
+### 1. Usage with `sqlite3`
+
+```ruby
+require 'sqlite3'
+require 'sqlite_web_vfs'
+require 'uri'
+
+chinook_url = "https://github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite"
+encoded_url = URI.encode_www_form_component(chinook_url)
+web_uri = "file:/__web__?vfs=web&mode=ro&immutable=1&web_url=#{encoded_url}"
+
+db = SQLite3::Database.new(':memory:')
+SQLiteWebVFS::Loader.load(db)
+puts "HTTP VFS extension loaded."
+
+db.execute("ATTACH DATABASE ? AS remote", [web_uri])
+puts "Remote database attached as 'remote'."
+
+album_count = db.get_first_value("SELECT COUNT(*) FROM remote.Album")
+puts "Found #{album_count} albums in the remote Chinook database."
+```
+
+### 2. Usage with `sqlite3-ffi`
+
+```ruby
+require 'sqlite3-ffi'
+require 'sqlite_web_vfs'
+require 'uri'
+
+chinook_url = "https://github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite"
+encoded_url = URI.encode_www_form_component(chinook_url)
+web_uri = "file:/__web__?vfs=web&mode=ro&immutable=1&web_url=#{encoded_url}"
+
+db = SQLite3::Database.new(':memory:')
+SQLiteWebVFS::Loader.load(db)
+puts "HTTP VFS extension loaded into FFI driver."
+
+db.execute("ATTACH DATABASE ? AS remote", [web_uri])
+puts "Remote database attached as 'remote'."
+
+album_count = db.execute("SELECT COUNT(*) FROM remote.Album").first.first
+puts "Found #{album_count} albums in the remote Chinook database."
+```
+
+### 3. Usage with SQLite CLI
+
+**Note**: Extension loading requires SQLite to be compiled with extension support. Many system SQLite builds disable this for security (compiled with `OMIT_LOAD_EXTENSION`). If `.load` is unavailable, use the Ruby examples above instead.
+
+For SQLite builds with extension support (use Homebrew's sqlite3 on macOS):
+
+```bash
+# macOS: Use Homebrew's sqlite3 which supports extensions
+/opt/homebrew/bin/sqlite3 -cmd ".load $(ruby -r sqlite_web_vfs -e 'puts SQLiteWebVFS::Loader.built_extension_path')" -cmd "ATTACH DATABASE 'file:/__web__?vfs=web&mode=ro&immutable=1&web_url=https%3A//github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite' AS remote;" ":memory:"
+
+# Or with PATH updated to use Homebrew's sqlite3:
+sqlite3 -cmd ".load $(ruby -r sqlite_web_vfs -e 'puts SQLiteWebVFS::Loader.built_extension_path')" -cmd "ATTACH DATABASE 'file:/__web__?vfs=web&mode=ro&immutable=1&web_url=https%3A//github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite' AS remote;" ":memory:"
+```
+
+Then query the remote database:
+```sql
+SELECT COUNT(*) FROM remote.Album;
+```
+
+To check if your SQLite supports extensions:
+```bash
+sqlite3 ":memory:" "PRAGMA compile_options;" | grep -i load
+```
+If you see `OMIT_LOAD_EXTENSION`, use the Ruby API instead.
+
+## Development
+- Build: `gem build` then install the gem.
+- Tests: `bundle exec rspec` (CI runs on Amazon Linux 2023 and macOS).
+
+## License
+- Vendored C/C++ from `mlin/sqlite_web_vfs`. See `LICENSE-3RD-PARTY.md`.
+- This gem includes code from `mlin/sqlite_web_vfs`, used under its original license.
+

data/examples/sqlite3_example.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'sqlite3'
+require 'sqlite_web_vfs'
+require 'uri'
+
+chinook_url = 'https://github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite'
+encoded_url = URI.encode_www_form_component(chinook_url)
+web_uri = "file:/__web__?vfs=web&mode=ro&immutable=1&web_url=#{encoded_url}"
+
+db = SQLite3::Database.new(':memory:')
+SQLiteWebVFS::Loader.load(db)
+puts '✅ HTTP VFS extension loaded.'
+
+db.execute('ATTACH DATABASE ? AS remote', [web_uri])
+puts "✅ Remote database attached as 'remote'."
+
+album_count = db.get_first_value('SELECT COUNT(*) FROM remote.Album')
+puts "💿 Found #{album_count} albums in the remote Chinook database."
+
+db.close

data/examples/sqlite3_ffi_example.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+begin
+  require 'sqlite3-ffi'
+rescue LoadError
+  require 'sqlite3/ffi'
+end
+require 'sqlite_web_vfs'
+require 'uri'
+
+chinook_url = 'https://github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite'
+encoded_url = URI.encode_www_form_component(chinook_url)
+web_uri = "file:/__web__?vfs=web&mode=ro&immutable=1&web_url=#{encoded_url}"
+
+db = SQLite3::Database.new(':memory:')
+SQLiteWebVFS::Loader.load(db)
+puts '✅ HTTP VFS extension loaded into FFI driver.'
+
+db.execute('ATTACH DATABASE ? AS remote', [web_uri])
+puts "✅ Remote database attached as 'remote'."
+
+album_count = db.execute('SELECT COUNT(*) FROM remote.Album').first.first
+puts "💿 Found #{album_count} albums in the remote Chinook database."
+
+db.close

data/ext/sqlite_web_vfs/Makefile

@@ -0,0 +1,267 @@
+
+SHELL = /bin/sh
+
+# V=0 quiet, V=1 verbose.  other values don't work.
+V = 0
+Q1 = $(V:1=)
+Q = $(Q1:0=@)
+ECHO1 = $(V:1=@ :)
+ECHO = $(ECHO1:0=@ echo)
+NULLCMD = :
+
+#### Start of system configuration section. ####
+
+srcdir = .
+topdir = /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX15.5.sdk/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/include/ruby-2.6.0
+hdrdir = $(topdir)
+arch_hdrdir = /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX15.5.sdk/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/include/ruby-2.6.0/universal-darwin24
+PATH_SEPARATOR = :
+VPATH = $(srcdir):$(arch_hdrdir)/ruby:$(hdrdir)/ruby
+prefix = $(DESTDIR)/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr
+rubysitearchprefix = $(rubylibprefix)/$(sitearch)
+rubyarchprefix = $(rubylibprefix)/$(arch)
+rubylibprefix = $(libdir)/$(RUBY_BASE_NAME)
+exec_prefix = $(prefix)
+vendorarchhdrdir = $(vendorhdrdir)/$(sitearch)
+sitearchhdrdir = $(sitehdrdir)/$(sitearch)
+rubyarchhdrdir = $(rubyhdrdir)/$(arch)
+vendorhdrdir = $(rubyhdrdir)/vendor_ruby
+sitehdrdir = $(rubyhdrdir)/site_ruby
+rubyhdrdir = $(includedir)/$(RUBY_VERSION_NAME)
+vendorarchdir = $(vendorlibdir)/$(sitearch)
+vendorlibdir = $(vendordir)/$(ruby_version)
+vendordir = $(rubylibprefix)/vendor_ruby
+sitearchdir = $(sitelibdir)/$(sitearch)
+sitelibdir = $(sitedir)/$(ruby_version)
+sitedir = $(DESTDIR)/Library/Ruby/Site
+rubyarchdir = $(rubylibdir)/$(arch)
+rubylibdir = $(rubylibprefix)/$(ruby_version)
+sitearchincludedir = $(includedir)/$(sitearch)
+archincludedir = $(includedir)/$(arch)
+sitearchlibdir = $(libdir)/$(sitearch)
+archlibdir = $(libdir)/$(arch)
+ridir = $(datarootdir)/$(RI_BASE_NAME)
+mandir = $(DESTDIR)/usr/share/man
+localedir = $(datarootdir)/locale
+libdir = $(exec_prefix)/lib
+psdir = $(docdir)
+pdfdir = $(docdir)
+dvidir = $(docdir)
+htmldir = $(docdir)
+infodir = $(DESTDIR)/usr/share/info
+docdir = $(datarootdir)/doc/$(PACKAGE)
+oldincludedir = $(DESTDIR)/usr/include
+includedir = $(DESTDIR)/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX15.5.sdk$(prefix)/include
+runstatedir = $(localstatedir)/run
+localstatedir = $(prefix)/var
+sharedstatedir = $(prefix)/com
+sysconfdir = $(DESTDIR)/Library/Ruby/Site
+datadir = $(datarootdir)
+datarootdir = $(prefix)/share
+libexecdir = $(exec_prefix)/libexec
+sbindir = $(exec_prefix)/sbin
+bindir = $(exec_prefix)/bin
+archdir = $(rubyarchdir)
+
+
+CC_WRAPPER = 
+CC = xcrun clang
+CXX = xcrun clang++
+LIBRUBY = $(LIBRUBY_SO)
+LIBRUBY_A = lib$(RUBY_SO_NAME)-static.a
+LIBRUBYARG_SHARED = -l$(RUBY_SO_NAME)
+LIBRUBYARG_STATIC = -l$(RUBY_SO_NAME)-static -framework Security -framework Foundation $(MAINLIBS)
+empty =
+OUTFLAG = -o $(empty)
+COUTFLAG = -o $(empty)
+CSRCFLAG = $(empty)
+
+RUBY_EXTCONF_H = 
+cflags   = $(optflags) $(debugflags) $(warnflags)
+cxxflags = $(optflags) $(debugflags) $(warnflags)
+optflags = 
+debugflags = -g
+warnflags = 
+cppflags = 
+CCDLFLAGS = 
+CFLAGS   = $(CCDLFLAGS)  -g -Os -pipe -DHAVE_GCC_ATOMIC_BUILTINS -fno-typed-memory-operations -fno-typed-cxx-new-delete -DUSE_FFI_CLOSURE_ALLOC  $(ARCH_FLAG)
+INCFLAGS = -I. -I$(arch_hdrdir) -I$(hdrdir)/ruby/backward -I$(hdrdir) -I$(srcdir) -I/opt/homebrew/opt/sqlite/include
+DEFS     = 
+CPPFLAGS = -DHAVE_SQLITE3_H -DHAVE_CURL_CURL_H -I/Users/denis/Documents/labtiva/sqlite_web_vfs/ext/sqlite_web_vfs/upstream/include -D_XOPEN_SOURCE -D_DARWIN_C_SOURCE -D_DARWIN_UNLIMITED_SELECT -D_REENTRANT $(DEFS) $(cppflags)
+CXXFLAGS = $(CCDLFLAGS)  -g -Os -pipe   $(ARCH_FLAG)
+ldflags  = -L. -L/AppleInternal/Library/BuildRoots/4~B5FAugAunRW9OK7YcFNXDBTTVy6DXTYoxzE3ORQ/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX15.6.Internal.sdk/usr/local/lib -L/opt/homebrew/opt/sqlite/lib
+dldflags = $(ARCH_FLAG)             -undefined dynamic_lookup 
+ARCH_FLAG = 
+DLDFLAGS = $(ldflags) $(dldflags) $(ARCH_FLAG)
+LDSHARED = $(CC) -dynamic -bundle
+LDSHAREDXX = $(CXX) -dynamic -bundle
+AR = libtool -static
+EXEEXT = 
+
+RUBY_INSTALL_NAME = $(RUBY_BASE_NAME)
+RUBY_SO_NAME = ruby.2.6
+RUBYW_INSTALL_NAME = 
+RUBY_VERSION_NAME = $(RUBY_BASE_NAME)-$(ruby_version)
+RUBYW_BASE_NAME = rubyw
+RUBY_BASE_NAME = ruby
+
+arch = universal-darwin24
+sitearch = $(arch)
+ruby_version = 2.6.0
+ruby = $(bindir)/$(RUBY_BASE_NAME)
+RUBY = $(ruby)
+ruby_headers = $(hdrdir)/ruby.h $(hdrdir)/ruby/backward.h $(hdrdir)/ruby/ruby.h $(hdrdir)/ruby/defines.h $(hdrdir)/ruby/missing.h $(hdrdir)/ruby/intern.h $(hdrdir)/ruby/st.h $(hdrdir)/ruby/subst.h $(arch_hdrdir)/ruby/config.h
+
+RM = rm -f
+RM_RF = $(RUBY) -run -e rm -- -rf
+RMDIRS = rmdir -p
+MAKEDIRS = mkdir -p
+INSTALL = /usr/bin/install -c
+INSTALL_PROG = $(INSTALL) -m 0755
+INSTALL_DATA = $(INSTALL) -m 644
+COPY = cp
+TOUCH = exit >
+
+#### End of system configuration section. ####
+
+preload = 
+libpath = . $(libdir) /Users/denis/Documents/labtiva/sqlite_web_vfs/ext/sqlite_web_vfs/upstream/lib
+LIBPATH =  -L. -L$(libdir) -L/Users/denis/Documents/labtiva/sqlite_web_vfs/ext/sqlite_web_vfs/upstream/lib
+DEFFILE = 
+
+CLEANFILES = mkmf.log
+DISTCLEANFILES = 
+DISTCLEANDIRS = 
+
+extout = 
+extout_prefix = 
+target_prefix = /sqlite_web_vfs
+LOCAL_LIBS = 
+LIBS = $(LIBRUBYARG_SHARED) -lcurl -lsqlite3  -lsqlite3  
+ORIG_SRCS = _wrap_web_vfs.cc shim.c
+SRCS = $(ORIG_SRCS) 
+OBJS = _wrap_web_vfs.o shim.o
+HDRS = $(srcdir)/readerwriterqueue.h
+LOCAL_HDRS = 
+TARGET = sqlite_web_vfs
+TARGET_NAME = sqlite_web_vfs
+TARGET_ENTRY = Init_$(TARGET_NAME)
+DLLIB = $(TARGET).bundle
+EXTSTATIC = 
+STATIC_LIB = 
+
+TIMESTAMP_DIR = .
+BINDIR        = $(bindir)
+RUBYCOMMONDIR = $(sitedir)$(target_prefix)
+RUBYLIBDIR    = $(sitelibdir)$(target_prefix)
+RUBYARCHDIR   = $(sitearchdir)$(target_prefix)
+HDRDIR        = $(rubyhdrdir)/ruby$(target_prefix)
+ARCHHDRDIR    = $(rubyhdrdir)/$(arch)/ruby$(target_prefix)
+TARGET_SO_DIR =
+TARGET_SO     = $(TARGET_SO_DIR)$(DLLIB)
+CLEANLIBS     = $(TARGET_SO) 
+CLEANOBJS     = *.o  *.bak
+
+all:    $(DLLIB)
+static: $(STATIC_LIB)
+.PHONY: all install static install-so install-rb
+.PHONY: clean clean-so clean-static clean-rb
+
+clean-static::
+clean-rb-default::
+clean-rb::
+clean-so::
+clean: clean-so clean-static clean-rb-default clean-rb
+		-$(Q)$(RM) $(CLEANLIBS) $(CLEANOBJS) $(CLEANFILES) .*.time
+
+distclean-rb-default::
+distclean-rb::
+distclean-so::
+distclean-static::
+distclean: clean distclean-so distclean-static distclean-rb-default distclean-rb
+		-$(Q)$(RM) Makefile $(RUBY_EXTCONF_H) conftest.* mkmf.log
+		-$(Q)$(RM) core ruby$(EXEEXT) *~ $(DISTCLEANFILES)
+		-$(Q)$(RMDIRS) $(DISTCLEANDIRS) 2> /dev/null || true
+
+realclean: distclean
+install: install-so install-rb
+
+install-so: $(DLLIB) $(TIMESTAMP_DIR)/.sitearchdir.-.sqlite_web_vfs.time
+	$(INSTALL_PROG) $(DLLIB) $(RUBYARCHDIR)
+clean-static::
+	-$(Q)$(RM) $(STATIC_LIB)
+install-rb: pre-install-rb do-install-rb install-rb-default
+install-rb-default: pre-install-rb-default do-install-rb-default
+pre-install-rb: Makefile
+pre-install-rb-default: Makefile
+do-install-rb:
+do-install-rb-default:
+pre-install-rb-default:
+	@$(NULLCMD)
+$(TIMESTAMP_DIR)/.sitearchdir.-.sqlite_web_vfs.time:
+	$(Q) $(MAKEDIRS) $(@D) $(RUBYARCHDIR)
+	$(Q) $(TOUCH) $@
+
+site-install: site-install-so site-install-rb
+site-install-so: install-so
+site-install-rb: install-rb
+
+.SUFFIXES: .c .m .cc .mm .cxx .cpp .o .S
+
+.cc.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -c $(CSRCFLAG)$<
+
+.cc.S:
+	$(ECHO) translating $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -S $(CSRCFLAG)$<
+
+.mm.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -c $(CSRCFLAG)$<
+
+.mm.S:
+	$(ECHO) translating $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -S $(CSRCFLAG)$<
+
+.cxx.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -c $(CSRCFLAG)$<
+
+.cxx.S:
+	$(ECHO) translating $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -S $(CSRCFLAG)$<
+
+.cpp.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -c $(CSRCFLAG)$<
+
+.cpp.S:
+	$(ECHO) translating $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -S $(CSRCFLAG)$<
+
+.c.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CC) $(INCFLAGS) $(CPPFLAGS) $(CFLAGS) $(COUTFLAG)$@ -c $(CSRCFLAG)$<
+
+.c.S:
+	$(ECHO) translating $(<)
+	$(Q) $(CC) $(INCFLAGS) $(CPPFLAGS) $(CFLAGS) $(COUTFLAG)$@ -S $(CSRCFLAG)$<
+
+.m.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CC) $(INCFLAGS) $(CPPFLAGS) $(CFLAGS) $(COUTFLAG)$@ -c $(CSRCFLAG)$<
+
+.m.S:
+	$(ECHO) translating $(<)
+	$(Q) $(CC) $(INCFLAGS) $(CPPFLAGS) $(CFLAGS) $(COUTFLAG)$@ -S $(CSRCFLAG)$<
+
+$(TARGET_SO): $(OBJS) Makefile
+	$(ECHO) linking shared-object sqlite_web_vfs/$(DLLIB)
+	-$(Q)$(RM) $(@)
+	$(Q) $(LDSHAREDXX) -o $@ $(OBJS) $(LIBPATH) $(DLDFLAGS) $(LOCAL_LIBS) $(LIBS)
+	$(Q) $(POSTLINK)
+
+
+
+$(OBJS): $(HDRS) $(ruby_headers)

data/ext/sqlite_web_vfs/extconf.rb

@@ -0,0 +1,177 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'mkmf'
+require 'fileutils'
+require 'shellwords'
+require 'net/http'
+require 'uri'
+# NOTE: mkmf will compile all .c/.cc files in this directory.
+
+# Build settings
+dir_config('sqlite3')
+
+def darwin?
+  (/darwin/ =~ RUBY_PLATFORM) != nil
+end
+
+def linux?
+  (/linux/ =~ RUBY_PLATFORM) != nil
+end
+
+# Allow overriding via env or flags
+sqlite_prefix = with_config('sqlite3-dir') || ENV.fetch('SQLITE3_DIR', nil)
+if sqlite_prefix
+  inc = File.join(sqlite_prefix, 'include')
+  lib = File.join(sqlite_prefix, 'lib')
+  dir_config('sqlite3', inc, lib)
+  ENV['PKG_CONFIG_PATH'] = [File.join(lib, 'pkgconfig'), ENV.fetch('PKG_CONFIG_PATH', nil)].compact.join(':')
+end
+
+# HTTP implementation uses lazy-loaded libcurl when HTTP_LAZYCURL is defined.
+# This avoids requiring libcurl at link time; on Linux we still need -ldl.
+# Set required flags via mkmf CONFIG instead of globals
+CONFIG['CPPFLAGS'] = [CONFIG['CPPFLAGS'], '-DHTTP_LAZYCURL'].compact.join(' ')
+CONFIG['CXXFLAGS'] = [CONFIG['CXXFLAGS'], '-std=c++17', '-O2', '-DHTTP_LAZYCURL'].compact.join(' ')
+
+have_library('dl') if linux?
+have_library('pthread') if linux?
+
+bundled = ENV['WEBVFS_FORCE_BUNDLED'] == '1'
+
+if bundled
+  warn "\n==> WEBVFS_FORCE_BUNDLED=1 set: building against bundled SQLite amalgamation.\n    " \
+       'This is for advanced users and may not interoperate with other SQLite users in-process.'
+  # Download the amalgamation
+  require 'tmpdir'
+  require 'zlib'
+  require 'rubygems/package'
+
+  amalgamation_version = ENV['SQLITE_AMALGAMATION_VERSION'] || '3460000' # 3.46.0
+  base = "sqlite-amalgamation-#{amalgamation_version}"
+  url  = "https://www.sqlite.org/2024/#{base}.zip"
+  dest_dir = File.expand_path('sqlite-amalgamation', __dir__)
+  FileUtils.mkdir_p(dest_dir)
+  zip_path = File.join(dest_dir, "#{base}.zip")
+  begin
+    uri = URI.parse(url)
+    Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+      http.request(Net::HTTP::Get.new(uri)) do |response|
+        abort "Failed to download SQLite amalgamation from #{url}: #{response.code} #{response.message}" unless response.is_a?(Net::HTTPSuccess)
+        File.open(zip_path, 'wb') do |file|
+          response.read_body { |chunk| file.write(chunk) }
+        end
+      end
+    end
+    # unzip minimal without external tools
+    require 'zip'
+  rescue LoadError
+    # Fallback: try system unzip
+  end
+  if system('ruby', '-e', 'require "zip"; puts "ok"', out: File::NULL, err: File::NULL)
+    require 'zip'
+    Zip::File.open(zip_path) do |zip|
+      %w[sqlite3.c sqlite3.h sqlite3ext.h].each do |f|
+        e = zip.find_entry("#{base}/#{f}")
+        File.write(File.join(dest_dir, f), e.get_input_stream.read)
+      end
+    end
+  else
+    abort "Failed to extract SQLite amalgamation from #{zip_path}. Install 'rubyzip' or 'unzip'." unless system("unzip -o #{Shellwords.escape(zip_path)} -d #{Shellwords.escape(dest_dir)}")
+    %w[sqlite3.c sqlite3.h sqlite3ext.h].each do |f|
+      src = File.join(dest_dir, base, f)
+      FileUtils.cp(src, File.join(dest_dir, f))
+    end
+  end
+  # NOTE: Generate a tiny wrapper C file so mkmf picks up the amalgamation without globals
+  wrap_amalg = File.join(__dir__, '_wrap_sqlite3_amalgamation.c')
+  File.write(wrap_amalg, "#include \"sqlite-amalgamation/sqlite3.c\"\n") unless File.exist?(wrap_amalg)
+  # No need to link to system sqlite3 now
+else
+  # Try pkg-config after probing Homebrew keg
+  begin
+    brew_sqlite = `brew --prefix sqlite 2>/dev/null`.strip
+    unless brew_sqlite.to_s.empty?
+      ENV['PKG_CONFIG_PATH'] = [File.join(brew_sqlite, 'lib/pkgconfig'), ENV.fetch('PKG_CONFIG_PATH', nil)].compact.join(':')
+      pkg_config('sqlite3') || true
+    end
+  rescue
+  end
+  # Try initial detection
+  sqlite_ok = have_header('sqlite3.h') && have_library('sqlite3', 'sqlite3_libversion_number')
+  # On macOS, also probe Homebrew keg paths if initial check failed or pkg-config lacked cflags
+  if !sqlite_ok && darwin?
+    begin
+      brew_sqlite = `brew --prefix sqlite 2>/dev/null`.strip
+      unless brew_sqlite.to_s.empty?
+        dir_config('sqlite3', File.join(brew_sqlite, 'include'), File.join(brew_sqlite, 'lib'))
+        ENV['PKG_CONFIG_PATH'] = [File.join(brew_sqlite, 'lib/pkgconfig'), ENV.fetch('PKG_CONFIG_PATH', nil)].compact.join(':')
+        pkg_config('sqlite3') || true
+        sqlite_ok = have_header('sqlite3.h') && have_library('sqlite3', 'sqlite3_libversion_number')
+      end
+    rescue
+    end
+  end
+  unless sqlite_ok
+    msg = <<~SQLITE_HELP
+
+      Could not find SQLite3 development headers and library.
+
+      Install SQLite and retry:
+        - macOS (Homebrew):
+            brew install sqlite
+        - Amazon Linux 2023:
+            sudo dnf install sqlite-devel
+
+      Or specify a custom path:
+        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
+    SQLITE_HELP
+    abort msg
+  end
+end
+
+# Ensure libcurl headers are available for compilation (lazy loaded at runtime)
+curl_ok = have_header('curl/curl.h')
+if !curl_ok && darwin?
+  begin
+    brew_curl = `brew --prefix curl 2>/dev/null`.strip
+    unless brew_curl.to_s.empty?
+      dir_config('curl', File.join(brew_curl, 'include'), File.join(brew_curl, 'lib'))
+      ENV['PKG_CONFIG_PATH'] = [File.join(brew_curl, 'lib/pkgconfig'), ENV.fetch('PKG_CONFIG_PATH', nil)].compact.join(':')
+      pkg_config('libcurl') || true
+      curl_ok = have_header('curl/curl.h')
+    end
+  rescue
+  end
+end
+unless curl_ok
+  msg = <<~CURL_HELP
+
+    Could not find libcurl development headers (curl/curl.h).
+
+    Install libcurl and retry:
+      - macOS (Homebrew):
+          brew install curl
+      - Amazon Linux 2023:
+          sudo dnf install libcurl-devel
+  CURL_HELP
+  abort msg
+end
+
+# On Linux, also link against libcurl to satisfy symbol resolution when loaders enforce RTLD_NOW.
+have_library('curl', 'curl_easy_perform')
+
+# Sources: C shim + vendored upstream C++ implementation
+# NOTE: Generate a tiny wrapper to compile the upstream C++ file from this dir
+wrap_web_vfs = File.join(__dir__, '_wrap_web_vfs.cc')
+File.write(wrap_web_vfs, "#include \"upstream/web_vfs.cc\"\n") unless File.exist?(wrap_web_vfs)
+
+# Ensure a C++ compiler is set and upstream headers are on include path
+CONFIG['CXX'] ||= with_config('CXX', ENV['CXX'] || 'c++')
+upstream_dir = File.expand_path('upstream', __dir__)
+dir_config('upstream_headers', upstream_dir, nil)
+
+create_makefile('sqlite_web_vfs/sqlite_web_vfs')

data/ext/sqlite_web_vfs/readerwriterqueue.h

@@ -0,0 +1,5 @@
+#ifndef SQLITE_WEB_VFS_FORWARD_READERWRITERQUEUE_H
+#define SQLITE_WEB_VFS_FORWARD_READERWRITERQUEUE_H
+#include "upstream/readerwriterqueue.h"
+#endif
+

data/ext/sqlite_web_vfs/shim.c

@@ -0,0 +1,16 @@
+#include <ruby.h>
+#include <sqlite3.h>
+
+// Upstream extension init symbol from mlin/sqlite_web_vfs
+extern int sqlite3_webvfs_init(sqlite3 *db, char **pzErrMsg, const sqlite3_api_routines *pApi);
+
+// Provide the default SQLite extension entry point name so Database#load_extension (1-arg)
+// can load this extension into an already-open connection.
+int sqlite3_extension_init(sqlite3 *db, char **pzErrMsg, const sqlite3_api_routines *pApi) {
+  return sqlite3_webvfs_init(db, pzErrMsg, pApi);
+}
+
+void Init_sqlite_web_vfs(void) {
+  // Register the upstream VFS as an auto-extension so it's available to all connections
+  sqlite3_auto_extension((void (*)(void))sqlite3_webvfs_init);
+}