litestream 0.1.0-x86_64-darwin → 0.2.0-x86_64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf0407988688ebeb20c51953e897c23c0db0c7eb236f4c9fcf78b85dc3ff98d0
-  data.tar.gz: 770df356f3cad5e47133cddb110b604836029ba77ef28c72efca1dff3417ae5d
+  metadata.gz: b23ace1583cc1f70cb4e86d05762dedd415530f8f2d6e8725730a6602fe3582e
+  data.tar.gz: 3628916497bfc379f6a54df34b2979c67077bb1e2bf43a1a62dc3222d2cdc372
 SHA512:
-  metadata.gz: 1ae6adb42343659680977d9c3bb717da4e2197cf6135ae8c05661bdff2502f300eac09c1052497d0179c37667d55389734af0d154088aafe781b5a1233a414c8
-  data.tar.gz: 57d61463a1e414e888ae31c616d24cc3f7dbca5b32cdc69f31f564782c415ab7a3420fc27282b115d015b8268a5dd80ee59227b0310f1baa040265c541165562
+  metadata.gz: e5e44dee7e00de45d94f04ec7939387a070c8ce94b9c0509c5456efc080620f3d19f8abcaaec4afc202110f3e010249a7eb6c6142ae47219762fc2410b417652
+  data.tar.gz: b439d6594e7ae2069b7b6119018377a6bed320a60225d9bf49ee3c6a6261e9efa2b63d8561867f2274d09b58c7e90b9929aef3bd7d2b056b2a55fae3c316ce30

data/README.md

@@ -1,34 +1,98 @@
-# Litestream
+# litestream-ruby
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/litestream`. To experiment with that code, run `bin/console` for an interactive prompt.
+[Litestream](https://litestream.io/) is a standalone streaming replication tool for SQLite. This gem provides a Ruby interface to Litestream.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+    $ bundle add litestream
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+    $ gem install litestream
+
+After installing the gem, run the installer:
+
+    $ rails generate litestream:install
+
+The installer will create a configuration file at `config/litestream.yml`, an initializer file for configuring the gem at `config/initializers/litestream.rb`, as well as a `Procfile` so that you can run the Litestream replication process alongside your Rails application in production.
+
+This gem wraps the standalone executable version of the [Litestream](https://litestream.io/install/source/) utility. These executables are platform specific, so there are actually separate underlying gems per platform, but the correct gem will automatically be picked for your platform. Litestream itself doesn't support Windows, so this gem doesn't either.
+
+Supported platforms are:
+
+* arm64-darwin (macos-arm64)
+* x86_64-darwin (macos-x64)
+* arm64-linux (linux-arm64)
+* x86_64-linux (linux-x64)
+
+### Using a local installation of `litestream`
+
+If you are not able to use the vendored standalone executables (for example, if you're on an unsupported platform), you can use a local installation of the `litestream` executable by setting an environment variable named `LITESTREAM_INSTALL_DIR` to the directory containing the executable.
+
+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
+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
+LITESTREAM_INSTALL_DIR=.bin
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+### Configuration
+
+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 one application database 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:
+
+```yaml
+dbs:
+  - path: $LITESTREAM_DATABASE_PATH
+    replicas:
+      - url: $LITESTREAM_REPLICA_URL
+        access-key-id: $LITESTREAM_ACCESS_KEY_ID
+        secret-access-key: $LITESTREAM_SECRET_ACCESS_KEY
+```
+
+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.database_path = ActiveRecord::Base.connection_db_config.database
+  config.replica_url = litestream_credentials.replica_url
+  config.replica_key_id = litestream_credentials.replica_key_id
+  config.replica_access_key = litestream_credentials.replica_access_key
+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/).
+
+### Replication
+
+By default, the gem will create or append to a `Procfile` to start the Litestream process via the gem's provided `litestream:replicate` rake task. This rake task will automatically load the configuration file and set the environment variables before starting the Litestream process.
+
+Again, however, you can take full manual control over the replication process and simply run the `litestream replicate --config config/litestream.yml` command to start the Litestream process. Since the gem installs the native executable via Bundler, the `litestream` command will be available in your `PATH`.
+
+The full set of commands available to the `litestream` executable are covered in Litestream's [command reference](https://litestream.io/reference/). Currently, only the `replicate` command is provided as a rake task by the gem.
 
 ## Development
 
 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 release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+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).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/litestream. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/litestream/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/fractaledmind/litestream-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/fractaledmind/litestream-ruby/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -36,4 +100,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Litestream project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/litestream/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Litestream project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/fractaledmind/litestream-ruby/blob/main/CODE_OF_CONDUCT.md).

data/exe/litestream

@@ -8,6 +8,6 @@ begin
   puts command.inspect
   exec(*command)
 rescue Litestream::Commands::UnsupportedPlatformException, Litestream::Commands::ExecutableNotFoundException => e
-  STDERR.puts("ERROR: " + e.message)
+  warn("ERROR: " + e.message)
   exit 1
 end

data/lib/litestream/commands.rb

@@ -17,61 +17,70 @@ module Litestream
     class DirectoryNotFoundException < StandardError
     end
 
-    class << self
-      def platform
-        [:cpu, :os].map { |m| Gem::Platform.local.send(m) }.join("-")
-      end
+    def self.platform
+      [:cpu, :os].map { |m| Gem::Platform.local.send(m) }.join("-")
+    end
 
-      def executable(exe_path: DEFAULT_DIR)
-        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}"
-            exe_path = litestream_install_dir
-            exe_file = File.expand_path(File.join(litestream_install_dir, "litestream"))
-          else
-            raise DirectoryNotFoundException, <<~MESSAGE
-              LITESTREAM_INSTALL_DIR is set to #{litestream_install_dir}, but that directory does not exist.
-            MESSAGE
-          end
+    def self.executable(exe_path: DEFAULT_DIR)
+      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}"
+          exe_path = litestream_install_dir
+          exe_file = File.expand_path(File.join(litestream_install_dir, "litestream"))
         else
-          if Litestream::Upstream::NATIVE_PLATFORMS.keys.none? { |p| Gem::Platform.match_gem?(Gem::Platform.new(p), GEM_NAME) }
-            raise UnsupportedPlatformException, <<~MESSAGE
-              litestream-ruby does not support the #{platform} platform
-              Please install litestream following instructions at https://litestream.io/install
-            MESSAGE
-          end
-
-          exe_file = Dir.glob(File.expand_path(File.join(exe_path, "*", "litestream"))).find do |f|
-            Gem::Platform.match_gem?(Gem::Platform.new(File.basename(File.dirname(f))), GEM_NAME)
-          end
+          raise DirectoryNotFoundException, <<~MESSAGE
+            LITESTREAM_INSTALL_DIR is set to #{litestream_install_dir}, but that directory does not exist.
+          MESSAGE
+        end
+      else
+        if Litestream::Upstream::NATIVE_PLATFORMS.keys.none? { |p| Gem::Platform.match_gem?(Gem::Platform.new(p), GEM_NAME) }
+          raise UnsupportedPlatformException, <<~MESSAGE
+            litestream-ruby does not support the #{platform} platform
+            Please install litestream following instructions at https://litestream.io/install
+          MESSAGE
         end
 
-        if exe_file.nil? || !File.exist?(exe_file)
-          raise ExecutableNotFoundException, <<~MESSAGE
-            Cannot find the litestream executable for #{platform} in #{exe_path}
+        exe_file = Dir.glob(File.expand_path(File.join(exe_path, "*", "litestream"))).find do |f|
+          Gem::Platform.match_gem?(Gem::Platform.new(File.basename(File.dirname(f))), GEM_NAME)
+        end
+      end
 
-            If you're using bundler, please make sure you're on the latest bundler version:
+      if exe_file.nil? || !File.exist?(exe_file)
+        raise ExecutableNotFoundException, <<~MESSAGE
+          Cannot find the litestream executable for #{platform} in #{exe_path}
 
-                gem install bundler
-                bundle update --bundler
+          If you're using bundler, please make sure you're on the latest bundler version:
 
-            Then make sure your lock file includes this platform by running:
+              gem install bundler
+              bundle update --bundler
 
-                bundle lock --add-platform #{platform}
-                bundle install
+          Then make sure your lock file includes this platform by running:
 
-            See `bundle lock --help` output for details.
+              bundle lock --add-platform #{platform}
+              bundle install
 
-            If you're still seeing this message after taking those steps, try running
-            `bundle config` and ensure `force_ruby_platform` isn't set to `true`. See
-            https://github.com/fractaledmind/litestream-ruby#check-bundle_force_ruby_platform
-            for more details.
-          MESSAGE
-        end
+          See `bundle lock --help` output for details.
 
-        exe_file
+          If you're still seeing this message after taking those steps, try running
+          `bundle config` and ensure `force_ruby_platform` isn't set to `true`. See
+          https://github.com/fractaledmind/litestream-ruby#check-bundle_force_ruby_platform
+          for more details.
+        MESSAGE
       end
+
+      exe_file
+    end
+
+    def self.replicate
+      return if Litestream.configuration.nil?
+
+      ENV["LITESTREAM_DATABASE_PATH"] = Litestream.configuration.database_path
+      ENV["LITESTREAM_REPLICA_URL"] = Litestream.configuration.replica_url
+      ENV["LITESTREAM_ACCESS_KEY_ID"] = Litestream.configuration.replica_key_id
+      ENV["LITESTREAM_SECRET_ACCESS_KEY"] = Litestream.configuration.replica_access_key
+
+      system(executable, "replicate", "--config", Rails.root.join("config", "litestream.yml").to_s)
     end
   end
 end

data/lib/litestream/generators/litestream/install_generator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Litestream
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_config_file
+        template "litestream.yml", "config/litestream.yml"
+      end
+
+      def copy_initializer_file
+        template "litestream.rb", "config/initializers/litestream.rb"
+      end
+
+      def create_or_update_procfile
+        if File.exist?("Procfile")
+          append_to_file "Procfile", "litestream: bin/rails litestream:replicate"
+        else
+          create_file "Procfile" do
+            <<~PROCFILE
+              rails: bundle exec rails server --port $PORT
+              litestream: bin/rails litestream:replicate
+            PROCFILE
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,8 @@
+litestream_credentials = Rails.application.credentials.litestream
+
+Litestream.configure do |config|
+  config.database_path = ActiveRecord::Base.connection_db_config.database
+  config.replica_url = litestream_credentials.replica_url
+  config.replica_key_id = litestream_credentials.replica_key_id
+  config.replica_access_key = litestream_credentials.replica_access_key
+end

data/lib/litestream/generators/litestream/templates/litestream.yml

@@ -0,0 +1,6 @@
+dbs:
+  - path: $LITESTREAM_DATABASE_PATH
+    replicas:
+      - url: $LITESTREAM_REPLICA_URL
+        access-key-id: $LITESTREAM_ACCESS_KEY_ID
+        secret-access-key: $LITESTREAM_SECRET_ACCESS_KEY

data/lib/litestream/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Litestream
+  class Railtie < ::Rails::Railtie
+    # Load the `litestream:install` generator into the host Rails app
+    generators do
+      require_relative "generators/litestream/install_generator"
+    end
+
+    # Load the `litestream:env` Rake task into the host Rails app
+    rake_tasks do
+      load "tasks/litestream_tasks.rake"
+    end
+  end
+end

data/lib/litestream/upstream.rb

@@ -8,7 +8,7 @@ module Litestream
       "arm64-darwin" => "litestream-#{VERSION}-darwin-arm64.zip",
       "arm64-linux" => "litestream-#{VERSION}-linux-arm64.tar.gz",
       "x86_64-darwin" => "litestream-#{VERSION}-darwin-amd64.zip",
-      "x86_64-linux" => "litestream-#{VERSION}-linux-amd64.tar.gz",
+      "x86_64-linux" => "litestream-#{VERSION}-linux-amd64.tar.gz"
     }
   end
 end

data/lib/litestream/version.rb

@@ -1,3 +1,3 @@
 module Litestream
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/litestream.rb

@@ -1,8 +1,25 @@
 # frozen_string_literal: true
 
-require_relative "litestream/version"
-
 module Litestream
-  class Error < StandardError; end
-  # Your code goes here...
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
+
+  class Configuration
+    attr_accessor :database_path, :replica_url, :replica_key_id, :replica_access_key
+
+    def initialize
+      @mailer_sender = "donotreply@example.com"
+    end
+  end
 end
+
+require_relative "litestream/version"
+require_relative "litestream/upstream"
+require_relative "litestream/commands"
+require_relative "litestream/railtie" if defined?(::Rails::Railtie)

data/lib/tasks/litestream_tasks.rake

@@ -0,0 +1,21 @@
+namespace :litestream do
+  desc "Print the ENV variables needed for the Litestream config file"
+  task env: :environment do
+    if Litestream.configuration.nil?
+      warn "You have not configured the Litestream gem with any values to generate ENV variables"
+      next
+    end
+
+    puts "LITESTREAM_DATABASE_PATH=#{Litestream.configuration.database_path}"
+    puts "LITESTREAM_REPLICA_URL=#{Litestream.configuration.replica_url}"
+    puts "LITESTREAM_ACCESS_KEY_ID=#{Litestream.configuration.replica_key_id}"
+    puts "LITESTREAM_SECRET_ACCESS_KEY=#{Litestream.configuration.replica_access_key}"
+
+    true
+  end
+
+  desc ""
+  task replicate: :environment do
+    Litestream::Commands.replicate
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: litestream
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: x86_64-darwin
 authors:
 - Stephen Margheim
@@ -24,6 +24,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  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: sqlite3
+  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:
 email:
 - stephen.margheim@gmail.com
@@ -40,8 +68,13 @@ files:
 - exe/x86_64-darwin/litestream
 - lib/litestream.rb
 - lib/litestream/commands.rb
+- lib/litestream/generators/litestream/install_generator.rb
+- lib/litestream/generators/litestream/templates/litestream.rb
+- lib/litestream/generators/litestream/templates/litestream.yml
+- lib/litestream/railtie.rb
 - lib/litestream/upstream.rb
 - lib/litestream/version.rb
+- lib/tasks/litestream_tasks.rake
 homepage: https://github.com/fractaledmind/litestream-ruby
 licenses:
 - MIT