hotswap 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d4648f76060073d16f095250ed5e638c4150d5094069e839b2bce9b1b471852a
+  data.tar.gz: 592b37ce1c1f4691e9bb74d9606ef7727333a3b65f878ebff906084b9a56168e
+SHA512:
+  metadata.gz: 869189ee05937fab2b970e31b0cbd13c6a0f36d4d127b0dfb664c793ffd1b060d07050ad0563c1cb224c68187bfa178000305c2cb4e85dad1f0e336d842b69ec
+  data.tar.gz: 94f141f2bd7990c6a55a53b01c1491941179453361a014caf91dd2cb83f890026e9898e78b19a8e16f8a8890c175cc298efe1145616900a2eeb9149ffaa503c4

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brad Gessler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/exe/hotswap

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+
+require "socket"
+require "securerandom"
+
+socket_path = ENV.fetch("HOTSWAP_SOCKET", "tmp/sqlite3.sock")
+stderr_socket_path = ENV.fetch("HOTSWAP_STDERR_SOCKET", "tmp/sqlite3.stderr.sock")
+
+unless File.exist?(socket_path)
+  $stderr.puts "ERROR: socket not found at #{socket_path}"
+  exit 1
+end
+
+# Connect stderr socket first (if available) so it's registered before the command runs
+stderr_sock = nil
+stderr_key = SecureRandom.hex(8)
+if File.exist?(stderr_socket_path)
+  stderr_sock = UNIXSocket.new(stderr_socket_path)
+  stderr_sock.write("#{stderr_key}\n")
+end
+
+sock = UNIXSocket.new(socket_path)
+
+# Send command args with stderr key as first line
+args = ARGV.join(" ")
+args += " --stderr-key=#{stderr_key}" if stderr_sock
+sock.write(args + "\n")
+
+# Pipe stdin to socket (in background thread)
+writer = Thread.new do
+  IO.copy_stream($stdin, sock) rescue nil
+  sock.close_write rescue nil
+end
+
+# Pipe stderr socket to local stderr (in background thread)
+stderr_reader = nil
+if stderr_sock
+  stderr_reader = Thread.new do
+    IO.copy_stream(stderr_sock, $stderr) rescue nil
+  end
+end
+
+# Pipe socket output to stdout
+IO.copy_stream(sock, $stdout) rescue nil
+
+writer.join
+stderr_reader&.join
+stderr_sock&.close rescue nil
+sock.close rescue nil

data/lib/hotswap/cli.rb

@@ -0,0 +1,132 @@
+require "thor"
+require "tempfile"
+require "sqlite3"
+
+module Hotswap
+  class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "cp SRC DST", "Copy a database to/from the running server. Use 'database' to refer to the running database."
+    long_desc <<~DESC
+      Copy a SQLite database to or from the running server.
+
+      Use 'database' as a placeholder for the running server's database.
+      Use '-' for stdin/stdout.
+
+      Examples:
+
+        hotswap cp ./new.sqlite3 database     # replace the running database
+        hotswap cp database ./backup.sqlite3   # snapshot the running database
+        hotswap cp - database                  # read from stdin
+        hotswap cp database -                  # write to stdout
+    DESC
+    def cp(src, dst)
+      db_path = Hotswap.database_path
+      unless db_path
+        $stderr.write("ERROR: database_path not configured\n")
+        return
+      end
+
+      if src == "database" && dst == "database"
+        $stderr.write("ERROR: source and destination can't both be 'database'\n")
+        return
+      end
+
+      if dst == "database"
+        push_database(src, db_path)
+      elsif src == "database"
+        pull_database(dst, db_path)
+      else
+        $stderr.write("ERROR: one of src/dst must be 'database'\n")
+      end
+    end
+
+    desc "push", "Replace the running database from stdin"
+    def push
+      cp("-", "database")
+    end
+
+    desc "pull", "Snapshot the running database to stdout"
+    def pull
+      cp("database", "-")
+    end
+
+    desc "version", "Print the hotswap version"
+    def version
+      $stdout.write("hotswap #{Hotswap::VERSION}\n")
+    end
+
+    private
+
+    def push_database(src, db_path)
+      input = (src == "-") ? $stdin : File.open(src, "rb")
+
+      dir = File.dirname(db_path)
+      temp = Tempfile.new(["hotswap", ".sqlite3"], dir)
+      begin
+        IO.copy_stream(input, temp)
+        temp.close
+
+        db = SQLite3::Database.new(temp.path)
+        result = db.execute("PRAGMA integrity_check")
+        db.close
+        unless result == [["ok"]]
+          $stderr.write("ERROR: integrity check failed\n")
+          return
+        end
+
+        $stderr.write("Swapping database...\n")
+
+        Middleware::SWAP_LOCK.synchronize do
+          if defined?(ActiveRecord::Base)
+            ActiveRecord::Base.connection_handler.clear_all_connections!
+          end
+          File.rename(temp.path, db_path)
+        end
+
+        if defined?(ActiveRecord::Base)
+          ActiveRecord::Base.establish_connection
+        end
+
+        $stdout.write("OK\n")
+      rescue => e
+        $stderr.write("ERROR: #{e.message}\n")
+      ensure
+        input.close if input.is_a?(File)
+        temp.unlink if temp && File.exist?(temp.path)
+      end
+    end
+
+    def pull_database(dst, db_path)
+      unless File.exist?(db_path)
+        $stderr.write("ERROR: database file not found\n")
+        return
+      end
+
+      dir = File.dirname(db_path)
+      temp = Tempfile.new(["hotswap-pull", ".sqlite3"], dir)
+      begin
+        src_db = SQLite3::Database.new(db_path)
+        dst_db = SQLite3::Database.new(temp.path)
+        b = SQLite3::Backup.new(dst_db, "main", src_db, "main")
+        b.step(-1)
+        b.finish
+        dst_db.close
+        src_db.close
+
+        if dst == "-"
+          File.open(temp.path, "rb") { |f| IO.copy_stream(f, $stdout) }
+        else
+          FileUtils.cp(temp.path, dst)
+          $stderr.write("OK\n")
+        end
+      rescue => e
+        $stderr.write("ERROR: #{e.message}\n")
+      ensure
+        temp.unlink if temp && File.exist?(temp.path)
+      end
+    end
+  end
+end

data/lib/hotswap/middleware.rb

@@ -0,0 +1,13 @@
+module Hotswap
+  class Middleware
+    SWAP_LOCK = Mutex.new
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      SWAP_LOCK.synchronize { @app.call(env) }
+    end
+  end
+end

data/lib/hotswap/railtie.rb

@@ -0,0 +1,41 @@
+module Hotswap
+  class Railtie < Rails::Railtie
+    config.hotswap = ActiveSupport::OrderedOptions.new
+
+    initializer "hotswap.configure" do |app|
+      # Default database path from Rails config
+      if app.config.hotswap.database_path
+        Hotswap.database_path = app.config.hotswap.database_path
+      else
+        db_config = app.config.database_configuration[Rails.env]
+        if db_config && db_config["adapter"]&.include?("sqlite")
+          Hotswap.database_path = db_config["database"]
+        end
+      end
+
+      # Default socket paths
+      if app.config.hotswap.socket_path
+        Hotswap.socket_path = app.config.hotswap.socket_path
+      else
+        Hotswap.socket_path = File.join(app.root, "tmp", "sqlite3.sock")
+      end
+
+      if app.config.hotswap.stderr_socket_path
+        Hotswap.stderr_socket_path = app.config.hotswap.stderr_socket_path
+      else
+        Hotswap.stderr_socket_path = File.join(app.root, "tmp", "sqlite3.stderr.sock")
+      end
+    end
+
+    initializer "hotswap.middleware" do |app|
+      app.middleware.use Hotswap::Middleware
+    end
+
+    initializer "hotswap.socket_server" do
+      server = Hotswap::SocketServer.new
+      server.start
+
+      at_exit { server.stop }
+    end
+  end
+end

data/lib/hotswap/socket_server.rb

@@ -0,0 +1,127 @@
+require "socket"
+
+module Hotswap
+  class SocketServer
+    attr_reader :socket_path, :stderr_socket_path
+
+    def initialize(socket_path: Hotswap.socket_path, stderr_socket_path: Hotswap.stderr_socket_path)
+      @socket_path = socket_path
+      @stderr_socket_path = stderr_socket_path
+      @server = nil
+      @stderr_server = nil
+      @thread = nil
+      @stderr_clients = {}
+      @stderr_mutex = Mutex.new
+    end
+
+    def start
+      cleanup_stale_socket(@socket_path)
+      cleanup_stale_socket(@stderr_socket_path)
+
+      @server = UNIXServer.new(@socket_path)
+      @stderr_server = UNIXServer.new(@stderr_socket_path)
+
+      @thread = Thread.new { accept_loop }
+      @thread.report_on_exception = false
+      self
+    end
+
+    def stop
+      @server&.close
+      @stderr_server&.close
+      @thread&.kill
+      @stderr_mutex.synchronize { @stderr_clients.each_value(&:close) rescue nil }
+      [@socket_path, @stderr_socket_path].each do |path|
+        File.delete(path) if path && File.exist?(path)
+      end
+    end
+
+    private
+
+    def accept_loop
+      ios = [@server, @stderr_server]
+      loop do
+        readable, = IO.select(ios)
+        readable.each do |server|
+          client = server.accept
+          if server == @stderr_server
+            register_stderr_client(client)
+          else
+            Thread.new(client) { |sock| handle_connection(sock) }
+          end
+        end
+      end
+    rescue IOError, Errno::EBADF
+      # Server was closed, exit gracefully
+    end
+
+    def register_stderr_client(client)
+      # stderr client sends its PID on first line so we can match it
+      line = client.gets
+      return client.close unless line
+      key = line.strip
+      @stderr_mutex.synchronize { @stderr_clients[key] = client }
+    end
+
+    def take_stderr_client(key)
+      @stderr_mutex.synchronize { @stderr_clients.delete(key) }
+    end
+
+    def handle_connection(socket)
+      # First line is the command args
+      line = socket.gets
+      return unless line
+
+      parts = line.strip.split(/\s+/)
+      # Last part may be --stderr-key=<key>
+      stderr_key = nil
+      parts.reject! do |p|
+        if p.start_with?("--stderr-key=")
+          stderr_key = p.split("=", 2).last
+          true
+        end
+      end
+
+      # Wait briefly for the stderr client to connect
+      stderr_io = nil
+      if stderr_key
+        5.times do
+          stderr_io = take_stderr_client(stderr_key)
+          break if stderr_io
+          sleep 0.01
+        end
+      end
+
+      # Wire the socket as stdin/stdout and stderr socket as stderr for the CLI
+      old_stdin = $stdin
+      old_stdout = $stdout
+      old_stderr = $stderr
+      begin
+        $stdin = socket
+        $stdout = socket
+        $stderr = stderr_io || $stderr
+        Hotswap::CLI.start(parts)
+      ensure
+        $stdin = old_stdin
+        $stdout = old_stdout
+        $stderr = old_stderr
+      end
+    rescue => e
+      socket.write("ERROR: #{e.message}\n") rescue nil
+    ensure
+      stderr_io&.close rescue nil
+      socket.close rescue nil
+    end
+
+    def cleanup_stale_socket(path)
+      return unless File.exist?(path)
+      begin
+        test = UNIXSocket.new(path)
+        test.close
+        raise Hotswap::Error, "Socket #{path} is already in use"
+      rescue Errno::ECONNREFUSED, Errno::ENOENT
+        File.delete(path)
+      end
+    end
+  end
+end

data/lib/hotswap/version.rb

@@ -0,0 +1,3 @@
+module Hotswap
+  VERSION = "0.1.0"
+end

data/lib/hotswap.rb

@@ -0,0 +1,20 @@
+require_relative "hotswap/version"
+require_relative "hotswap/middleware"
+require_relative "hotswap/cli"
+require_relative "hotswap/socket_server"
+require_relative "hotswap/railtie" if defined?(Rails::Railtie)
+
+module Hotswap
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :database_path, :socket_path, :stderr_socket_path
+
+    def configure
+      yield self
+    end
+  end
+
+  self.socket_path = "tmp/sqlite3.sock"
+  self.stderr_socket_path = "tmp/sqlite3.stderr.sock"
+end

metadata

@@ -0,0 +1,187 @@
+--- !ruby/object:Gem::Specification
+name: hotswap
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Brad Gessler
+bindir: exe
+cert_chain: []
+date: 2026-02-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Swap a SQLite database on a running Rails server without restart. Requests
+  queue briefly during the swap, then resume on the new database.
+executables:
+- hotswap
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- exe/hotswap
+- lib/hotswap.rb
+- lib/hotswap/cli.rb
+- lib/hotswap/middleware.rb
+- lib/hotswap/railtie.rb
+- lib/hotswap/socket_server.rb
+- lib/hotswap/version.rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Hot-swap SQLite databases on a running Rails server
+test_files: []