litestream 0.13.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e4638f801b8e05319b2390a63422edd6778944bb053324aefdbd43f98a2f15c
-  data.tar.gz: ced2aa3f3648042bf7f2211c02b17db670d0cb8a0c86902067ab08688954cb37
+  metadata.gz: 006c5aaaf41fb59b8af8178c090aab72e78e8c586c83c59ddc25f25bc232ea98
+  data.tar.gz: a320d9128e3f5ad4c757c3463edebdbaecc7542c48008e5b1efa75dc53bdab1a
 SHA512:
-  metadata.gz: be394032aadcf1ae817248ea8e83c1d23433f007f133aa6a0680813d5dd360895695654295bc8f3c91bcd6e8608a973d85f64cea9bae85f64ab6597b2e541f40
-  data.tar.gz: f6e3e6681736fc683bc855ca85c8124cc003c94096406d0127932fc38815541c244a6c1a59ac88ba57d2f0a4816dac30ce25fb4deca4db5563484d99e3a20d6e
+  metadata.gz: f75e2d4e857f186de61a3665775d2018373509a4beeb448b11f404a5fa9b55d92da06eda2a75d09304d696b32f3e6e1d73423b851e44a77e7d31fe5bb4813cdd
+  data.tar.gz: abc842f2de56524cb9370eed3433c49491dc10adfe23f544b25ecd9017c8008ecbe378efe30a216340f97e6b79c9a138f8e88c03f4695c724427c6d12b22e259

data/README.md

@@ -80,24 +80,27 @@ LITESTREAM_INSTALL_DIR=.bin
 
 You configure the Litestream executable through the [`config/litestream.yml` file](https://litestream.io/reference/config/), which is a standard Litestream configuration file as if Litestream was running in a traditional installation.
 
-The gem streamlines the configuration process by providing a default configuration file for you. This configuration file will backup all SQLite databases defined in your `config/database.yml` file to one replication bucket. In order to ensure that no secrets are stored in plain-text in your repository, this configuration file leverages Litestream's support for environment variables. The default configuration file looks like this if you only have one SQLite database:
+The gem streamlines the configuration process by providing a default configuration file for you. This configuration file will backup all SQLite databases defined in your `config/database.yml` file to one replication bucket. In order to ensure that no secrets are stored in plain-text in your repository, this configuration file leverages Litestream's support for environment variables. Inspect which environment variables are available by running the `bin/rails litestream:env` command.
+
+The default configuration file looks like this if you only have one SQLite database:
 
 ```yaml
 dbs:
   - path: storage/production.sqlite3
     replicas:
       - type: s3
-        bucket: $LITESTREAM_REPLICA_BUCKET
         path: storage/production.sqlite3
+        bucket: $LITESTREAM_REPLICA_BUCKET
         access-key-id: $LITESTREAM_ACCESS_KEY_ID
         secret-access-key: $LITESTREAM_SECRET_ACCESS_KEY
 ```
 
 This is the default for Amazon S3. The full range of possible replica types (e.g. other S3-compatible object storage servers) are covered in Litestream's [replica guides](https://litestream.io/guides/#replica-guides).
 
-The gem also provides a default initializer file at `config/initializers/litestream.rb` that allows you to configure these three environment variables referenced in the configuration file in Ruby. By providing a Ruby interface to these environment variables, you can use any method of storing secrets that you prefer. For example, the default generated file uses Rails' encrypted credentials to store your secrets:
+The gem also provides a default initializer file at `config/initializers/litestream.rb` that allows you to configure various variables referenced in the configuration file in Ruby. By providing a Ruby interface to these environment variables, you can use your preferred method of storing secrets. For example, the default generated file uses Rails' encrypted credentials to store your secrets.
 
 ```ruby
+# config/initializers/litestream.rb
 Rails.application.configure do
   litestream_credentials = Rails.application.credentials.litestream
 
@@ -107,7 +110,21 @@ Rails.application.configure do
 end
 ```
 
-However, if you need manual control over the Litestream configuration, you can manually edit the `config/litestream.yml` file. The full range of possible configurations are covered in Litestream's [configuration reference](https://litestream.io/reference/config/).  NB: If you configure a longer `sync-interval`, you may need to adjust `replication_sleep` when calling `Litestream.verify!`.
+Outside of configuring Litestream's replication, you may also configure various other aspects of `litestream-ruby` itself. 
+
+```ruby
+# config/initializers/litestream.rb
+Rails.application.configure do
+  # ...
+
+  # Base controller used for Litestream dashboard
+  config.litestream.base_controller_class = "MyApplicationController"
+  # Set the location of the Litestream config
+  config.litestream.config_path = "config/litestream.yml"
+end
+```
+
+However, if you need manual control over the Litestream configuration, you can edit the `config/litestream.yml` file. The full range of possible configurations are covered in Litestream's [configuration reference](https://litestream.io/reference/config/).  
 
 ### Replication
 
@@ -232,6 +249,7 @@ You can verify the integrity of your backed-up databases using the gem's provide
 
 ```ruby
 Litestream.verify! "storage/production.sqlite3"
+Litestream.verify!(replication_sleep: 10) "storage/production.sqlite3"
 ```
 
 In order to verify that the backup for that database is both restorable and fresh, the method will add a new row to that database under the `_litestream_verification` table, which it will create if needed. It will then wait `replication_sleep` seconds (defaults to 10) to give the Litestream utility time to replicate that change to whatever storage providers you have configured. After that, it will download the latest backup from that storage provider and ensure that this verification row is present in the backup. If the verification row is _not_ present, the method will raise a `Litestream::VerificationFailure` exception. This check ensures that the restored database file:
@@ -242,6 +260,9 @@ In order to verify that the backup for that database is both restorable and fres
 
 After restoring the backup, the `Litestream.verify!` method will delete the restored database file. If you need the restored database file, use the `litestream:restore` rake task or `Litestream::Commands.restore` method instead.
 
+> [!NOTE]
+> If you configure Litestream's [`sync-interval`](https://litestream.io/reference/config/#replica-settings) to be longer than the default `replication_sleep` value of 10 seconds, you will need to adjust `replication_sleep` to a value larger than `sync-interval`; otherwise, `Litestream.verify!` may appear to fail where it actually simply didn't wait long enough for replication. 
+
 ### Dashboard
 
 The gem provides a web dashboard for monitoring the status of your Litestream replication. To mount the dashboard in your Rails application, add the following to your `config/routes.rb` file:
@@ -413,6 +434,8 @@ s3       a295b16a796689f3  1      0         2036     2024-04-17T00:01:19Z
 
 In addition to the provided rake tasks, you can also run Litestream commands directly from Ruby. The gem provides a `Litestream::Commands` module that wraps the Litestream CLI commands. This is particularly useful for the introspection commands, as you can use the output in your Ruby code.
 
+Commands raise `Litestream::Commands::CommandFailedException` when the Litestream binary exits non-zero, and the exception message includes stderr. Pass `json: true` to receive parsed JSON when using Litestream 0.5 or newer (Litestream 0.3 does not support the `-json` flag), and use `timeout:` to limit how many seconds a command may run.
+
 The `Litestream::Commands.databases` method returns an array of hashes with the "path" and "replicas" keys for each database:
 
 ```ruby
@@ -506,7 +529,7 @@ time=YYYY-MM-DDTHH:MM:SS level=INFO msg="replicating to" name=s3 type=s3 sync-in
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`.
+To install this gem onto your local machine, run `bundle exec rake install`. To download the Litestream binaries run `bundle exec rake download`.
 
 For maintainers, to release a new version, run `bin/release $VERSION`, which will create a git tag for the version, push git commits and tags, and push all of the platform-specific `.gem` files to [rubygems.org](https://rubygems.org).
 

data/app/controllers/litestream/application_controller.rb

@@ -1,5 +1,7 @@
 module Litestream
   class ApplicationController < Litestream.base_controller_class.constantize
+    layout "litestream/application"
+
     protect_from_forgery with: :exception
 
     if Litestream.password

data/app/controllers/litestream/restorations_controller.rb

@@ -9,7 +9,7 @@ module Litestream
       now = Time.now.utc.strftime("%Y%m%d%H%M%S")
       backup = File.join(dir, "#{base}-#{now}#{ext}")
 
-      Litestream::Commands.restore(database, async: false, **{"-o" => backup})
+      Litestream::Commands.restore(database, **{"-o" => backup})
 
       redirect_to root_path, notice: "Restored to <code>#{backup}</code>."
     end

data/lib/litestream/commands.rb

@@ -1,5 +1,6 @@
+require "json"
+require "open3"
 require_relative "upstream"
-require "logfmt"
 
 module Litestream
   module Commands
@@ -21,6 +22,27 @@ module Litestream
     # raised when a litestream command fails
     CommandFailedException = Class.new(StandardError)
 
+    # raised when a litestream command times out
+    CommandTimeoutException = Class.new(CommandFailedException)
+
+    module Output
+      class << self
+        def format(data)
+          return "" if data.nil? || data.empty?
+
+          headers = data.first.keys.map(&:to_s)
+          widths = headers.map.with_index { |h, i|
+            [h.length, data.map { |r| r[data.first.keys[i]].to_s.length }.max].max
+          }
+
+          format_str = widths.map { |w| "%-#{w}s" }.join("  ")
+          ([headers] + data.map(&:values)).map { |row|
+            sprintf(format_str, *row.map(&:to_s))
+          }.join("\n")
+        end
+      end
+    end
+
     class << self
       def platform
         [:cpu, :os].map { |m| Gem::Platform.local.send(m) }.join("-")
@@ -30,7 +52,10 @@ module Litestream
         litestream_install_dir = ENV["LITESTREAM_INSTALL_DIR"]
         if litestream_install_dir
           if File.directory?(litestream_install_dir)
-            warn "NOTE: using LITESTREAM_INSTALL_DIR to find litestream executable: #{litestream_install_dir}"
+            unless @litestream_install_dir_noted
+              warn "NOTE: using LITESTREAM_INSTALL_DIR to find litestream executable: #{litestream_install_dir}"
+              @litestream_install_dir_noted = true
+            end
             exe_path = litestream_install_dir
             exe_file = File.expand_path(File.join(litestream_install_dir, "litestream"))
           else
@@ -77,50 +102,62 @@ module Litestream
         exe_file
       end
 
+      # Replicate runs either as a child process or in the foreground, depending on the context.
+      # The Puma plugin starts it as a child and gets its pid back; the rake task runs it in the
+      # foreground and streams its output.
       def replicate(async: false, **argv)
-        execute("replicate", argv, async: async, tabled_output: false)
+        cmd = prepare("replicate", argv)
+        run_replicate(cmd, async: async)
+      rescue CommandFailedException
+        raise
+      rescue
+        raise CommandFailedException, "Failed to execute `#{cmd.join(" ")}`"
       end
 
-      def restore(database, async: false, **argv)
+      def restore(database, **argv)
         raise DatabaseRequiredException, "database argument is required for restore command, e.g. litestream:restore -- --database=path/to/database.sqlite" if database.nil?
-        argv.stringify_keys!
 
-        execute("restore", argv, database, async: async, tabled_output: false)
+        execute("restore", argv, database, tabled_output: false)
       end
 
-      def databases(async: false, **argv)
-        execute("databases", argv, async: async, tabled_output: true)
+      def databases(**argv)
+        execute("databases", argv)
       end
 
-      def generations(database, async: false, **argv)
+      def generations(database, **argv)
         raise DatabaseRequiredException, "database argument is required for generations command, e.g. litestream:generations -- --database=path/to/database.sqlite" if database.nil?
 
-        execute("generations", argv, database, async: async, tabled_output: true)
+        execute("generations", argv, database)
       end
 
-      def snapshots(database, async: false, **argv)
+      def snapshots(database, **argv)
         raise DatabaseRequiredException, "database argument is required for snapshots command, e.g. litestream:snapshots -- --database=path/to/database.sqlite" if database.nil?
 
-        execute("snapshots", argv, database, async: async, tabled_output: true)
+        execute("snapshots", argv, database)
       end
 
-      def wal(database, async: false, **argv)
+      def wal(database, **argv)
         raise DatabaseRequiredException, "database argument is required for wal command, e.g. litestream:wal -- --database=path/to/database.sqlite" if database.nil?
 
-        execute("wal", argv, database, async: async, tabled_output: true)
+        execute("wal", argv, database)
       end
 
       private
 
-      def execute(command, argv = {}, database = nil, async: false, tabled_output: false)
-        cmd = prepare(command, argv, database)
-        results = run(cmd, async: async, tabled_output: tabled_output)
-
-        if Array === results && results.one? && results[0]["level"] == "ERROR"
-          raise CommandFailedException, "Failed to execute `#{cmd.join(" ")}`; Reason: #{results[0]["error"]}"
+      def execute(command, argv = {}, database = nil, tabled_output: true)
+        argv = argv.stringify_keys
+        timeout = argv.delete("timeout")
+        output = if argv.delete("json")
+          argv["-json"] = nil
+          :json
+        elsif tabled_output
+          :table
         else
-          results
+          :raw
         end
+
+        cmd = prepare(command, argv, database)
+        run(cmd, output: output, timeout: timeout)
       end
 
       def prepare(command, argv = {}, database = nil)
@@ -132,28 +169,101 @@ module Litestream
 
         args = {
           "--config" => Litestream.config_path.to_s
-        }.merge(argv.stringify_keys).to_a.flatten.compact
-        cmd = [executable, command, *args, database].compact
+        }.merge(argv.stringify_keys).to_a.flatten.compact.map(&:to_s)
+        cmd = [executable, command, *args, database].compact.map(&:to_s)
         puts cmd.inspect if ENV["DEBUG"]
 
         cmd
       end
 
-      def run(cmd, async: false, tabled_output: false)
-        if async
-          # To release the resources of the Ruby process, just fork and exit.
-          # The forked process executes litestream and replaces itself.
-          exec(*cmd) if fork.nil?
-        else
-          stdout = `#{cmd.join(" ")}`.chomp
-          tabled_output ? text_table_to_hashes(stdout) : stdout.split("\n").map { Logfmt.parse(_1) }
+      # Runs the command without a shell and returns its parsed stdout. A non-zero
+      # exit raises with stderr. With a timeout, the command runs in its own
+      # process group and is killed (TERM, then KILL) when the deadline passes.
+      def run(cmd, output:, timeout: nil)
+        stdin, stdout, stderr, wait_thread = Open3.popen3(*cmd, pgroup: true)
+        stdin.close
+        stdout_reader = Thread.new { stdout.read }
+        stderr_reader = Thread.new { stderr.read }
+
+        # The readers finish when the last process holding the pipes exits, so
+        # waiting on them covers descendants the direct child may have left behind.
+        unless wait_thread.join(timeout) && stdout_reader.join(timeout) && stderr_reader.join(timeout)
+          kill_process_group("TERM", wait_thread.pid)
+          wait_thread.join(1)
+          kill_process_group("KILL", wait_thread.pid)
+          wait_thread.join
+          [stdout_reader, stderr_reader].each(&:join)
+          raise CommandTimeoutException, "Failed to execute `#{cmd[1]}`: timed out after #{timeout} seconds"
+        end
+
+        status = wait_thread.value
+        unless status.success?
+          raise CommandFailedException, "Failed to execute `#{cmd[1]}` (exit status #{status.exitstatus}): #{stderr_reader.value.strip[0, 500]}"
         end
+
+        case output
+        when :json then parse_json(cmd, stdout_reader.value)
+        when :table then parse_table(stdout_reader.value)
+        else stdout_reader.value
+        end
+      ensure
+        [stdout_reader, stderr_reader].each { |reader| reader&.join }
+        [stdin, stdout, stderr].each { |io| io&.close unless io&.closed? }
+      end
+
+      # macOS answers EPERM rather than ESRCH when every process left in the
+      # group has exited but not yet been reaped.
+      def kill_process_group(signal, pid)
+        Process.kill(signal, -pid)
+      rescue Errno::ESRCH, Errno::EPERM
+      end
+
+      # Two opt-in restore skips (-if-db-not-exists when the output exists,
+      # -if-replica-exists with no backups) exit 0 and print one logfmt line on
+      # stdout instead of JSON. They come back as {"skipped" => true, "message" => ...}.
+      def parse_json(cmd, stdout)
+        stdout = stdout.strip
+        return if stdout.empty?
+        return JSON.parse(stdout) if stdout.start_with?("{", "[")
+
+        skipped = stdout.match(/\Atime=\S+ level=\S+ msg=(?:"([^"]*)"|(\S+))/)
+        return {"skipped" => true, "message" => skipped[1] || skipped[2]} if skipped
+
+        raise CommandFailedException, "Unexpected output from `#{cmd[1]}`: #{stdout.lines.first.to_s.strip[0, 200]}"
       end
 
-      def text_table_to_hashes(string)
-        keys, *rows = string.split("\n").map { _1.split(/\s+/) }
+      def parse_table(stdout)
+        keys, *rows = stdout.strip.split("\n").map { _1.split(/\s+/) }
+        return [] unless keys
+
         rows.map { keys.zip(_1).to_h }
       end
+
+      # Async replication returns the pid of the litestream process itself so a
+      # supervisor can signal and wait on it. Process.spawn is fork-and-exec in
+      # one call, so the pid it returns is the one that becomes litestream. The
+      # previous `exec(*cmd) if fork.nil?` also execs in a child but returns
+      # into the parent too, and the Puma plugin wrapped that in a fork of its
+      # own, so it recorded a pid that exited immediately while the daemon was
+      # reparented to init and outlived Puma.
+      def run_replicate(cmd, async:)
+        if async
+          Process.spawn(*cmd)
+        else
+          # When running in-process, we capture output continuously and write to stdout.
+          IO.popen(cmd, err: [:child, :out]) do |io|
+            io.each_line { |line| puts line }
+          end
+          status = $?
+          # `replicate` runs until it is signalled, so a signal is how it is
+          # meant to end. A non-zero exit is litestream failing to start or
+          # dying on its own, which is invisible today: the task exits 0 and a
+          # supervisor sees a clean stop rather than a crash to restart.
+          if status && !status.success? && !status.signaled?
+            raise CommandFailedException, "Failed to execute `replicate` (exit status #{status.exitstatus})"
+          end
+        end
+      end
     end
   end
 end

data/lib/litestream/generators/litestream/templates/initializer.rb

@@ -5,29 +5,41 @@
 # or some other mechanism where the values are only available at runtime.
 
 Rails.application.configure do
-  # An example of using Rails encrypted credentials to configure Litestream.
+  # Configure Litestream through environment variables. Use Rails encrypted credentials for secrets.
   # litestream_credentials = Rails.application.credentials.litestream
 
-  # Replica-specific bucket location.
-  # This will be your bucket's URL without the `https://` prefix.
+  # Replica-specific bucket location. This will be your bucket's URL without the `https://` prefix.
   # For example, if you used DigitalOcean Spaces, your bucket URL could look like:
+  #
   #   https://myapp.fra1.digitaloceanspaces.com
+  #
   # And so you should set your `replica_bucket` to:
+  #
   #   myapp.fra1.digitaloceanspaces.com
-  # Litestream supports Azure Blog Storage, Backblaze B2, DigitalOcean Spaces,
-  # Scaleway Object Storage, Google Cloud Storage, Linode Object Storage, and
-  # any SFTP server.
-  # In this example, we are using Rails encrypted credentials to store the URL to
-  # our storage provider bucket.
+  #
   # config.litestream.replica_bucket = litestream_credentials&.replica_bucket
-
-  # Replica-specific authentication key.
-  # Litestream needs authentication credentials to access your storage provider bucket.
-  # In this example, we are using Rails encrypted credentials to store the access key ID.
+  #
+  # Replica-specific authentication key. Litestream needs authentication credentials to access your storage provider bucket.
   # config.litestream.replica_key_id = litestream_credentials&.replica_key_id
-
-  # Replica-specific secret key.
-  # Litestream needs authentication credentials to access your storage provider bucket.
-  # In this example, we are using Rails encrypted credentials to store the secret access key.
+  #
+  # Replica-specific secret key. Litestream needs authentication credentials to access your storage provider bucket.
   # config.litestream.replica_access_key = litestream_credentials&.replica_access_key
+  #
+  # Replica-specific region. Set the bucket’s region. Only used for AWS S3 & Backblaze B2.
+  # config.litestream.replica_region = "us-east-1"
+  #
+  # Replica-specific endpoint. Set the endpoint URL of the S3-compatible service. Only required for non-AWS services.
+  # config.litestream.replica_endpoint = "endpoint.your-objectstorage.com"
+
+  # Configure the default Litestream config path
+  # config.config_path = Rails.root.join("config", "litestream.yml")
+
+  # Configure the Litestream dashboard
+  #
+  # Set the default base controller class
+  # config.litestream.base_controller_class = "MyApplicationController"
+  #
+  # Set authentication credentials for Litestream dashboard
+  # config.litestream.username = litestream_credentials&.username
+  # config.litestream.password = litestream_credentials&.password
 end

data/lib/litestream/version.rb

@@ -1,3 +1,3 @@
 module Litestream
-  VERSION = "0.13.0"
+  VERSION = "0.15.0"
 end

data/lib/litestream.rb

@@ -1,10 +1,23 @@
 # frozen_string_literal: true
 
+require "etc"
 require "sqlite3"
+require "time"
 
 module Litestream
   VerificationFailure = Class.new(StandardError)
 
+  PROCESS_STATES = {
+    "D" => "uninterruptible",
+    "I" => "idle",
+    "R" => "running",
+    "S" => "sleeping",
+    "T" => "stopped",
+    "U" => "uninterruptible",
+    "Z" => "zombie"
+  }.freeze
+  private_constant :PROCESS_STATES
+
   class << self
     attr_writer :configuration
 
@@ -33,8 +46,7 @@ module Litestream
     end
   end
 
-  mattr_writer :username, :password, :queue, :replica_bucket, :replica_region, :replica_endpoint, :replica_key_id, :replica_access_key, :systemctl_command,
-    :config_path
+  mattr_writer :username, :password, :queue, :replica_bucket, :replica_region, :replica_endpoint, :replica_key_id, :replica_access_key, :systemctl_command, :config_path
   mattr_accessor :base_controller_class, default: "::ApplicationController"
 
   class << self
@@ -164,30 +176,58 @@ module Litestream
       info
     end
 
+    # Linux has every process under /proc, even in images that ship no `ps`
+    # (Debian slim) or BusyBox's, which lacks `-x` and `lstart` (Alpine).
     def process_info
-      litestream_replicate_ps = `ps -ax | grep litestream | grep replicate`
-      exit_code = $?.exitstatus
-      return unless exit_code.zero?
+      File.directory?("/proc/self") ? proc_process_info : ps_process_info
+    end
 
-      info = {}
-      litestream_replicate_ps.chomp.split("\n").each do |line|
-        next unless line.include?("litestream replicate")
-
-        pid, * = line.split(" ")
-        info[:pid] = pid
-        state, _, lstart = `ps -o "state,lstart" #{pid}`.chomp.split("\n").last.partition(/\s+/)
-
-        info[:status] = case state[0]
-        when "I" then "idle"
-        when "R" then "running"
-        when "S" then "sleeping"
-        when "T" then "stopped"
-        when "U" then "uninterruptible"
-        when "Z" then "zombie"
-        end
-        info[:started] = DateTime.strptime(lstart.strip, "%a %b %d %H:%M:%S %Y")
+    def proc_process_info(proc_dir = "/proc")
+      boot_time = File.foreach(File.join(proc_dir, "stat")).grep(/\Abtime /).first.split.last.to_i
+
+      Dir.glob(File.join(proc_dir, "[0-9]*")).each do |dir|
+        executable, command = File.read(File.join(dir, "cmdline")).split("\0")
+        next unless File.basename(executable.to_s) == "litestream" && command == "replicate"
+
+        # Fields are counted after the command name's closing paren, since the
+        # name itself may contain spaces and parens.
+        state, *fields = File.read(File.join(dir, "stat")).rpartition(")").last.split
+        start_ticks = fields[18].to_i
+
+        return {
+          pid: File.basename(dir),
+          status: PROCESS_STATES[state[0]],
+          started: Time.at(boot_time + start_ticks.fdiv(Etc.sysconf(Etc::SC_CLK_TCK))).to_datetime
+        }
+      rescue SystemCallError
+        # the process exited while being read, or belongs to another user
+        next
       end
-      info
+      nil
+    end
+
+    # macOS. The command name is matched on its own so that a shell or editor
+    # whose arguments mention "litestream replicate" is not mistaken for it.
+    def ps_process_info
+      output = `ps -axo pid=,stat=,lstart=,comm=`
+      return unless $?.success?
+
+      output.each_line do |line|
+        # lstart is always five words ("Mon Jul  1 11:10:58 2024"); comm is last
+        # because it may contain spaces.
+        pid, state, *lstart, command = line.strip.split(" ", 8)
+        next unless File.basename(command.to_s) == "litestream"
+        next unless `ps -o args= -p #{pid}`.match?(/litestream replicate(?: |$)/)
+
+        return {
+          pid: pid,
+          status: PROCESS_STATES[state[0]],
+          started: Time.strptime(lstart.join(" "), "%a %b %d %H:%M:%S %Y").to_datetime
+        }
+      end
+      nil
+    rescue Errno::ENOENT
+      nil
     end
   end
 end

data/lib/puma/plugin/litestream.rb

@@ -2,17 +2,13 @@ require "puma/plugin"
 
 # Copied from https://github.com/rails/solid_queue/blob/15408647f1780033dad223d3198761ea2e1e983e/lib/puma/plugin/solid_queue.rb
 Puma::Plugin.create do
-  attr_reader :puma_pid, :litestream_pid, :log_writer
+  attr_reader :litestream_pid, :log_writer
 
   def start(launcher)
     @log_writer = launcher.log_writer
-    @puma_pid = $$
 
     launcher.events.on_booted do
-      @litestream_pid = fork do
-        Thread.new { monitor_puma }
-        Litestream::Commands.replicate(async: true)
-      end
+      @litestream_pid = Litestream::Commands.replicate(async: true)
 
       in_background do
         monitor_litestream
@@ -33,10 +29,6 @@ Puma::Plugin.create do
   rescue Errno::ECHILD, Errno::ESRCH
   end
 
-  def monitor_puma
-    monitor(:puma_dead?, "Detected Puma has gone away, stopping Litestream...")
-  end
-
   def monitor_litestream
     monitor(:litestream_dead?, "Detected Litestream has gone away, stopping Puma...")
   end
@@ -59,10 +51,6 @@ Puma::Plugin.create do
     true
   end
 
-  def puma_dead?
-    Process.ppid != puma_pid
-  end
-
   def log(...)
     log_writer.log(...)
   end

data/lib/tasks/litestream_tasks.rake

@@ -12,83 +12,61 @@ namespace :litestream do
 
   desc 'Monitor and continuously replicate SQLite databases defined in your config file, for example `rake litestream:replicate -- -exec "foreman start"`'
   task replicate: :environment do
-    options = {}
-    if (separator_index = ARGV.index("--"))
-      ARGV.slice(separator_index + 1, ARGV.length)
-        .map { |pair| pair.split("=") }
-        .each { |opt| options[opt[0]] = opt[1] || nil }
-    end
-    options.symbolize_keys!
+    options = parse_argv_options
 
-    Litestream::Commands.replicate(async: true, **options)
+    Litestream::Commands.replicate(**options)
   end
 
   desc "Restore a SQLite database from a Litestream replica, for example `rake litestream:restore -- -database=storage/production.sqlite3`"
   task restore: :environment do
-    options = {}
-    if (separator_index = ARGV.index("--"))
-      ARGV.slice(separator_index + 1, ARGV.length)
-        .map { |pair| pair.split("=") }
-        .each { |opt| options[opt[0]] = opt[1] || nil }
-    end
-    database = options.delete("--database") || options.delete("-database")
-    options.symbolize_keys!
+    options = parse_argv_options
+    database = options.delete(:"--database") || options.delete(:"-database")
 
-    Litestream::Commands.restore(database, async: true, **options)
+    puts Litestream::Commands.restore(database, **options)
   end
 
   desc "List all databases and associated replicas in the config file, for example `rake litestream:databases -- -no-expand-env`"
   task databases: :environment do
-    options = {}
-    if (separator_index = ARGV.index("--"))
-      ARGV.slice(separator_index + 1, ARGV.length)
-        .map { |pair| pair.split("=") }
-        .each { |opt| options[opt[0]] = opt[1] || nil }
-    end
-    options.symbolize_keys!
+    options = parse_argv_options
 
-    Litestream::Commands.databases(async: true, **options)
+    puts Litestream::Commands::Output.format(Litestream::Commands.databases(**options))
   end
 
   desc "List all generations for a database or replica, for example `rake litestream:generations -- -database=storage/production.sqlite3`"
   task generations: :environment do
-    options = {}
-    if (separator_index = ARGV.index("--"))
-      ARGV.slice(separator_index + 1, ARGV.length)
-        .map { |pair| pair.split("=") }
-        .each { |opt| options[opt[0]] = opt[1] || nil }
-    end
-    database = options.delete("--database") || options.delete("-database")
-    options.symbolize_keys!
+    options = parse_argv_options
+    database = options.delete(:"--database") || options.delete(:"-database")
 
-    Litestream::Commands.generations(database, async: true, **options)
+    puts Litestream::Commands::Output.format(Litestream::Commands.generations(database, **options))
   end
 
   desc "List all snapshots for a database or replica, for example `rake litestream:snapshots -- -database=storage/production.sqlite3`"
   task snapshots: :environment do
-    options = {}
-    if (separator_index = ARGV.index("--"))
-      ARGV.slice(separator_index + 1, ARGV.length)
-        .map { |pair| pair.split("=") }
-        .each { |opt| options[opt[0]] = opt[1] || nil }
-    end
-    database = options.delete("--database") || options.delete("-database")
-    options.symbolize_keys!
+    options = parse_argv_options
+    database = options.delete(:"--database") || options.delete(:"-database")
 
-    Litestream::Commands.snapshots(database, async: true, **options)
+    puts Litestream::Commands::Output.format(Litestream::Commands.snapshots(database, **options))
   end
 
   desc "List all wal files for a database or replica, for example `rake litestream:wal -- -database=storage/production.sqlite3`"
   task wal: :environment do
+    options = parse_argv_options
+    database = options.delete(:"--database") || options.delete(:"-database")
+
+    puts Litestream::Commands::Output.format(
+      Litestream::Commands.wal(database, **options)
+    )
+  end
+
+  private
+
+  def parse_argv_options
     options = {}
     if (separator_index = ARGV.index("--"))
       ARGV.slice(separator_index + 1, ARGV.length)
         .map { |pair| pair.split("=") }
         .each { |opt| options[opt[0]] = opt[1] || nil }
     end
-    database = options.delete("--database") || options.delete("-database")
     options.symbolize_keys!
-
-    Litestream::Commands.wal(database, async: true, **options)
   end
 end

metadata

@@ -1,28 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: litestream
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Stephen Margheim
 bindir: exe
 cert_chain: []
-date: 2025-06-03 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: logfmt
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.0.10
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.0.10
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -37,6 +23,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+  force_ruby_platform: false
 - !ruby/object:Gem::Dependency
   name: actionpack
   requirement: !ruby/object:Gem::Requirement
@@ -51,6 +38,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
+  force_ruby_platform: false
 - !ruby/object:Gem::Dependency
   name: actionview
   requirement: !ruby/object:Gem::Requirement
@@ -65,8 +53,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
+  force_ruby_platform: false
 - !ruby/object:Gem::Dependency
-  name: activesupport
+  name: activejob
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -79,8 +68,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
+  force_ruby_platform: false
 - !ruby/object:Gem::Dependency
-  name: activejob
+  name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -93,6 +83,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
+  force_ruby_platform: false
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
@@ -107,20 +98,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
-- !ruby/object:Gem::Dependency
-  name: rubyzip
-  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'
+  force_ruby_platform: false
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -136,7 +114,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: sqlite3
+  name: rubyzip
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -200,7 +178,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.3
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Integrate Litestream with the RubyGems infrastructure.
 test_files: []