litestream 0.11.2 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59bbfcde749c016674729dc5b9b677e56cc5b31ec46727d490a19d481b928d61
-  data.tar.gz: 87812cd947c281c8212dd4bc414d7aad7e0e70d8d3ff2ffe3c4f07ec31c063fb
+  metadata.gz: 97ee67df39c929f752d8b6940cdf73394410faee3a1088d93be18accf45e6a02
+  data.tar.gz: d681a3c76f93071531027a341ff2bbaa6cddbe36878fee462425c5618efa848d
 SHA512:
-  metadata.gz: 13543423827364cbdb44b83674047549ce88df604017d2fca338a739e9453c097c6fec04aba2bf3621d3f725ced03fa62c20e132671d4e5f47616a1b1bc384b0
-  data.tar.gz: 52300ad4aa5f5b46026c9dbab2425461b3d68684a3e9cde5a462684366a90714971b3bd53afaa331eaf6fb8a754d78d0c4d6451d9769459cc621fc636de352a2
+  metadata.gz: 90604bae936d93428fccc63be8304445c5b8073e6ea63eb4311b45eee5673a0d425ec9b26331eee2b77ad7340f298882b602e968cda850869d075fff709e1dfa
+  data.tar.gz: 4315e85e29029800354e50d062e1ef1e91fc6fd590e4df5982605637dd5619d8852d808eb26d362409d7d3750461aec2f66b275629cd4f08952113db9c6b19ce

data/README.md

@@ -1,5 +1,29 @@
 # litestream-ruby
 
+<p>
+  <a href="https://rubygems.org/gems/litestream">
+  <img alt="GEM Version" src="https://img.shields.io/gem/v/litestream?color=168AFE&include_prereleases&logo=ruby&logoColor=FE1616">
+  </a>
+  <a href="https://rubygems.org/gems/litestream">
+    <img alt="GEM Downloads" src="https://img.shields.io/gem/dt/litestream?color=168AFE&logo=ruby&logoColor=FE1616">
+  </a>
+  <a href="https://github.com/testdouble/standard">
+    <img alt="Ruby Style" src="https://img.shields.io/badge/style-standard-168AFE?logo=ruby&logoColor=FE1616" />
+  </a>
+  <a href="https://github.com/fractaledmind/litestream-ruby/actions/workflows/main.yml">
+    <img alt="Tests" src="https://github.com/fractaledmind/litestream-ruby/actions/workflows/main.yml/badge.svg" />
+  </a>
+  <a href="https://github.com/sponsors/fractaledmind">
+    <img alt="Sponsors" src="https://img.shields.io/github/sponsors/fractaledmind?color=eb4aaa&logo=GitHub%20Sponsors" />
+  </a>
+  <a href="https://ruby.social/@fractaledmind">
+    <img alt="Ruby.Social Follow" src="https://img.shields.io/mastodon/follow/109291299520066427?domain=https%3A%2F%2Fruby.social&label=%40fractaledmind&style=social">
+  </a>
+  <a href="https://twitter.com/fractaledmind">
+    <img alt="Twitter Follow" src="https://img.shields.io/twitter/url?label=%40fractaledmind&style=social&url=https%3A%2F%2Ftwitter.com%2Ffractaledmind">
+  </a>
+</p>
+
 [Litestream](https://litestream.io/) is a standalone streaming replication tool for SQLite. This gem provides a Ruby interface to Litestream.
 
 ## Installation
@@ -28,10 +52,10 @@ This gem wraps the standalone executable version of the [Litestream](https://lit
 
 Supported platforms are:
 
-* arm64-darwin (macos-arm64)
-* x86_64-darwin (macos-x64)
-* arm64-linux (linux-arm64)
-* x86_64-linux (linux-x64)
+- arm64-darwin (macos-arm64)
+- x86_64-darwin (macos-x64)
+- arm64-linux (linux-arm64)
+- x86_64-linux (linux-x64)
 
 ### Using a local installation of `litestream`
 
@@ -39,13 +63,13 @@ If you are not able to use the vendored standalone executables (for example, if
 
 For example, if you've installed `litestream` so that the executable is found at `/usr/local/bin/litestream`, then you should set your environment variable like so:
 
-``` sh
+```sh
 LITESTREAM_INSTALL_DIR=/usr/local/bin
 ```
 
 This also works with relative paths. If you've installed into your app's directory at `./.bin/litestream`:
 
-``` sh
+```sh
 LITESTREAM_INSTALL_DIR=.bin
 ```
 
@@ -71,11 +95,12 @@ dbs:
 The gem also provides a default initializer file at `config/initializers/litestream.rb` that allows you to configure these four 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:
 
 ```ruby
-litestream_credentials = Rails.application.credentials.litestream
-Litestream.configure do |config|
-  config.replica_bucket = litestream_credentials.replica_bucket
-  config.replica_key_id = litestream_credentials.replica_key_id
-  config.replica_access_key = litestream_credentials.replica_access_key
+Rails.application.configure do
+  litestream_credentials = Rails.application.credentials.litestream
+
+  config.litestream.replica_bucket = litestream_credentials&.replica_bucket
+  config.litestream.replica_key_id = litestream_credentials&.replica_key_id
+  config.litestream.replica_access_key = litestream_credentials&.replica_access_key
 end
 ```
 
@@ -203,6 +228,119 @@ 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.
 
+### 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:
+
+```ruby
+authenticate :user, -> (user) { user.admin? } do
+  mount Litestream::Engine, at: "/litestream"
+end
+```
+
+> [!NOTE]
+> Be sure to [secure the dashboard](#authentication) in production.
+
+#### Authentication
+
+Litestream Rails does not restrict access out of the box. You must secure the dashboard yourself. However, it does provide basic HTTP authentication that can be used with basic authentication or Devise. All you need to do is setup a username and password.
+
+There are two ways to setup a username and password. First, you can use the `LITESTREAM_USERNAME` and `LITESTREAM_PASSWORD` environment variables:
+
+```ruby
+ENV["LITESTREAM_USERNAME"] = "frodo"
+ENV["LITESTREAM_PASSWORD"] = "ikeptmysecrets"
+```
+
+Second, you can configure the access credentials via the Rails configuration object, under the `litestream` key, in an initializer:
+
+```ruby
+# Set authentication credentials for Litestream
+config.litestream.username = Rails.application.credentials.litestream.username
+config.litestream.password = Rails.application.credentials.litestream.password
+```
+
+Either way, if you have set a username and password, Litestream will use basic HTTP authentication.
+
+> [!IMPORTANT]
+> If you have not set a username and password, Litestream will not require any authentication to view the dashboard.
+
+If you use Devise for authentication in your app, you can also restrict access to the dashboard by using their `authenticate` constraint in your routes file:
+
+```ruby
+authenticate :user, -> (user) { user.admin? } do
+  mount LitestreamRails::Engine, at: "/litestream"
+end
+```
+
+### Examples
+
+There is only one screen in the dashboard.
+
+- the show view of the Litestream replication process:
+
+![screenshot of the single page in the web dashboard, showing details of the Litestream replication process](images/show-screenshot.png)
+
+### Usage with API-only Applications
+
+If your Rails application is an API-only application (generated with the `rails new --api` command), you will need to add the following middleware to your `config/application.rb` file in order to use the dashboard UI provided by Litestream:
+
+```ruby
+# /config/application.rb
+config.middleware.use ActionDispatch::Cookies
+config.middleware.use ActionDispatch::Session::CookieStore
+config.middleware.use ActionDispatch::Flash
+```
+
+### Overwriting the views
+
+You can find the views in [`app/views`](https://github.com/fractaledmind/litestream/tree/main/app/views).
+
+```bash
+app/views/
+├── layouts
+│   └── litestream
+│       ├── _style.html
+│       └── application.html.erb
+└── litestream
+    └── processes
+        └── show.html.erb
+```
+
+You can always take control of the views by creating your own views and/or partials at these paths in your application. For example, if you wanted to overwrite the application layout, you could create a file at `app/views/layouts/litestream/application.html.erb`. If you wanted to remove the footer and the automatically disappearing flash messages, as one concrete example, you could define that file as:
+
+```erb
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Litestream</title>
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+
+    <%= render "layouts/litestream/style" %>
+  </head>
+  <body class="h-full flex flex-col">
+    <main class="container mx-auto max-w-4xl mt-4 px-2 grow">
+      <%= content_for?(:content) ? yield(:content) : yield %>
+    </main>
+
+    <div class="fixed top-0 left-0 right-0 text-center py-2">
+      <% if notice.present? %>
+        <p class="py-2 px-3 bg-green-50 text-green-500 font-medium rounded-lg inline-block">
+          <%= notice %>
+        </p>
+      <% end %>
+
+      <% if alert.present? %>
+        <p class="py-2 px-3 bg-red-50 text-red-500 font-medium rounded-lg inline-block">
+          <%= alert %>
+        </p>
+      <% end %>
+    </div>
+  </body>
+</html>
+```
+
 ### Introspection
 
 Litestream offers a handful of commands that allow you to introspect the state of your replication. The gem provides a few rake tasks that wrap these commands for you. For example, you can list the databases that Litestream is configured to replicate:
@@ -231,7 +369,7 @@ name  generation        lag     start                 end
 s3    a295b16a796689f3  -156ms  2024-04-17T00:01:19Z  2024-04-17T00:01:19Z
 ```
 
-Finally, you can list the snapshots available for a database:
+You can list the snapshots available for a database:
 
 ```shell
 bin/rails litestream:snapshots -- --database=storage/production.sqlite3
@@ -244,6 +382,19 @@ replica  generation        index  size     created
 s3       a295b16a796689f3  1      4645465  2024-04-17T00:01:19Z
 ```
 
+Finally, you can list the wal files available for a database:
+
+```shell
+bin/rails litestream:wal -- --database=storage/production.sqlite3
+```
+
+This command lists wal files available for that specified database:
+
+```
+replica  generation        index  offset    size     created
+s3       a295b16a796689f3  1      0         2036     2024-04-17T00:01:19Z
+```
+
 ### Running commands from Ruby
 
 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.
@@ -269,7 +420,14 @@ Litestream::Commands.snapshots('storage/production.sqlite3')
 # => [{"replica"=>"s3", "generation"=>"5f4341bc3d22d615", "index"=>"0", "size"=>"4645465", "created"=>"2024-04-17T19:48:09Z"}]
 ```
 
-You can also restore a database programatically using the `Litestream::Commands.restore` method, which returns the path to the restored database:
+The `Litestream::Commands.wal` method returns an array of hashes with the "replica", "generation", "index", "offset","size", and "created" keys for each wal:
+
+```ruby
+Litestream::Commands.wal('storage/production.sqlite3')
+# => [{"replica"=>"s3", "generation"=>"5f4341bc3d22d615", "index"=>"0",  "offset"=>"0", "size"=>"2036", "created"=>"2024-04-17T19:48:09Z"}]
+```
+
+You can also restore a database programmatically using the `Litestream::Commands.restore` method, which returns the path to the restored database:
 
 ```ruby
 Litestream::Commands.restore('storage/production.sqlite3')

data/lib/litestream/commands.rb

@@ -104,6 +104,12 @@ module Litestream
         execute("snapshots", argv, database, async: async, tabled_output: true)
       end
 
+      def wal(database, async: false, **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)
+      end
+
       private
 
       def execute(command, argv = {}, database = nil, async: false, tabled_output: false)

data/lib/litestream/version.rb

@@ -1,3 +1,3 @@
 module Litestream
-  VERSION = "0.11.2"
+  VERSION = "0.12.0"
 end

data/lib/litestream.rb

@@ -19,7 +19,7 @@ module Litestream
 
   def self.configure
     deprecator.warn(
-      'Configuring Litestream via Litestream.configure is deprecated. Use Rails.application.configure { config.litestream.* = ... } instead.',
+      "Configuring Litestream via Litestream.configure is deprecated. Use Rails.application.configure { config.litestream.* = ... } instead.",
       caller
     )
     self.configuration ||= Configuration.new
@@ -33,7 +33,7 @@ module Litestream
     end
   end
 
-  mattr_writer :username, :password, :queue, :replica_bucket, :replica_key_id, :replica_access_key
+  mattr_writer :username, :password, :queue, :replica_bucket, :replica_key_id, :replica_access_key, :systemctl_command
 
   class << self
     def verify!(database_path)
@@ -85,10 +85,14 @@ module Litestream
       @@replica_access_key || configuration.replica_access_key
     end
 
+    def systemctl_command
+      @@systemctl_command || "systemctl status litestream"
+    end
+
     def replicate_process
       info = {}
       if !`which systemctl`.empty?
-        systemctl_status = `systemctl status litestream`.chomp
+        systemctl_status = `#{Litestream.systemctl_command}`.chomp
         # ["● litestream.service - Litestream",
         #  "     Loaded: loaded (/lib/systemd/system/litestream.service; enabled; vendor preset: enabled)",
         #  "     Active: active (running) since Tue 2023-07-25 13:49:43 UTC; 8 months 24 days ago",
@@ -115,7 +119,7 @@ module Litestream
           end
         end
       else
-        litestream_replicate_ps = `ps -a | grep litestream | grep replicate`.chomp
+        litestream_replicate_ps = `ps -ax | grep litestream | grep replicate`.chomp
         litestream_replicate_ps.split("\n").each do |line|
           next unless line.include?("litestream replicate")
           pid, * = line.split(" ")

data/lib/tasks/litestream_tasks.rake

@@ -75,4 +75,18 @@ namespace :litestream do
 
     Litestream::Commands.snapshots(database, async: true, **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 = {}
+    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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: litestream
 version: !ruby/object:Gem::Version
-  version: 0.11.2
+  version: 0.12.0
 platform: ruby
 authors:
 - Stephen Margheim
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-06 00:00:00.000000000 Z
+date: 2024-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logfmt
@@ -203,7 +203,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.21
 signing_key:
 specification_version: 4
 summary: Integrate Litestream with the RubyGems infrastructure.