fly-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 22dd71b806c6b21ec539f8fbeaf046a502134c4fcff78c9294f32602ceb82760
+  data.tar.gz: a8840d2201bbc30175c36d30ed98833415a3621b42282c5bec8d787690a01f25
+SHA512:
+  metadata.gz: c1b8977226ee069be065c7b8baad3b242dfbe47560854ff3d1f20a6b02d95f3394a82f70fac4fb63c051387d5fb51cd16fc68b8f7ccf6d6323512e43c39559a0
+  data.tar.gz: 437c3d32c3498508d98cdc7ab96482260c93f367a754038985d124f1ffb05154cf4a3424650a0fb974d7f8c314188e9403556e8c7f00e150db7b5430b689b52b

data/.github/workflows/test.yml

@@ -0,0 +1,30 @@
+on: [push, pull_request]
+name: Test
+jobs:
+  test:
+    defaults:
+      run:
+        working-directory: fly-ruby
+    name: Test on ruby ${{ matrix.ruby_version }} with options - ${{ toJson(matrix.options) }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - { os: ubuntu-latest, ruby_version: 2.4 }
+          - { os: ubuntu-latest, ruby_version: 2.5 }
+          - { os: ubuntu-latest, ruby_version: 2.6 }
+          - { os: ubuntu-latest, ruby_version: 2.7 }
+          - { os: ubuntu-latest, ruby_version: '3.0' }
+          - { os: ubuntu-latest, ruby_version: jruby }
+    steps:
+    - name: Setup Ruby, JRuby and TruffleRuby
+      uses: ruby/setup-ruby@v1.75.0
+      with:
+        bundler: 1
+        ruby-version: ${{ matrix.ruby_version }}
+    - name: Checkout code
+      uses: actions/checkout@v2
+    - name: Run tests
+      run: |
+        bundle install --jobs 4 --retry 3
+        rake

data/.gitignore

@@ -0,0 +1,6 @@
+tmp
+log/
+.bundle
+Gemfile.lock
+.ruby-version
+*.gem

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gem 'rack-test'
+gem 'minitest'
+gemspec

data/LICENSE

@@ -0,0 +1,11 @@
+Copyright 2021 Joshua Sierles
+
+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,62 @@
+[![Test](https://github.com/superfly/fly-ruby/actions/workflows/test.yml/badge.svg)](https://github.com/superfly/fly-ruby/actions/workflows/test.yml)
+
+# Augment Ruby web apps on Fly.io
+
+[Fly.io](https://fly.io) offers a number of native features that can improve the perceived speed and observability of web applications with minimal configuration. This gem automates some of the work required to take advantage of these features.
+
+## Regional replicas 
+
+Running database replicas alongside your apps in multiple regions [is quick and easy with Fly's Postgresql cluster](https://fly.io/docs/getting-started/multi-region-databases/). This can increase the perceived speed of read-heavy applications.
+
+The catch: in most primary/replica setups, you have one writeable primary located in a specific region. Fly solves this by allowing requests to be *replyed*, at the routing layer, in another region.
+
+This repository includes the `fly-ruby` gem which will utomatcally route requests that write to the database to the primary region. It should work
+with any Rack-compatible Ruby framework.
+
+Currently, it does this by:
+
+* modifying the `DATABASE_URL` to point apps to their local regional replica
+* replaying non-idempotent (post/put/patch/delete) requests in the primary region
+* catching Postgresql exceptions caused by writes to a read-only replica, and replaying these requests in the primary region
+
+## Requirements
+
+You should have [setup a postgres cluster](https://fly.io/docs/getting-started/multi-region-databases/) on Fly. Then:
+
+* ensure that your Postgresql and application regions match up
+* ensure that no backup regions are assigned to your application
+* attach the Postgres cluster to your application with `fly postgres attach`
+
+Finally, set the `PRIMARY_REGION` environment variable in your app `fly.toml` to match the primary database region.
+
+## Installation
+
+Add to your Gemfile and `bundle install`:
+
+`gem "fly-ruby"`
+
+If you're on Rails, the middleware will insert itself automatically at the top of the Rack middleware stack.
+
+## Configuration
+
+Most values used by this middleware are configurable. On Rails, this might go in an initializer like `config/initializers/fly.rb`
+
+```
+Fly.configure do |c|
+  c.replay_threshold_in_seconds = 10
+end
+```
+
+See [the source code](https://github.com/soupedup/fly-rails/blob/main/lib/fly-rails/configuration.rb) for defaults and available configuration options.
+## Known issues
+
+This middleware send all requests to the primary if you do something like update a user's database session on every GET request.
+
+If your replica becomes writeable for some reason, your custer may get out of sync.
+
+## TODO
+
+Here are some ideas for improving this gem.
+
+* Add a helper to invoke ActiveJob, and possibly AR read/write split support, to send GET-originated writes to the primary database in the background
+

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/*.rb']
+  t.verbose = true
+end
+
+desc "Run tests"
+task default: :test

data/fly-ruby.gemspec

@@ -0,0 +1,17 @@
+require_relative 'lib/fly-ruby/version'
+
+Gem::Specification.new do |spec|
+  spec.name = "fly-ruby"
+  spec.version = Fly::VERSION
+  spec.authors = ["Joshua Sierles"]
+  spec.homepage = "https://github.com/superfly/fly-ruby"
+  spec.summary = "Augment Ruby web apps for deployment in Fly.io"
+  spec.description = "Automate the work requied to run Ruby apps against region-local databases on Fly.io"
+  spec.email = "joshua@hey.com"
+  spec.licenses = "BSD-3-Clause"
+  spec.platform = Gem::Platform::RUBY
+  spec.required_ruby_version = ">= 2.4"
+  spec.files = `git ls-files | grep -Ev '^(test)'`.split("\n")
+
+  spec.add_dependency "rack", "~> 2.0"
+end

data/lib/fly-ruby.rb

@@ -0,0 +1,33 @@
+require_relative "fly-ruby/configuration"
+require_relative "fly-ruby/regional_database"
+require "forwardable"
+
+if defined?(::Rails)
+  require_relative "fly-ruby/railtie"
+end
+
+module Fly
+  class << self
+    extend Forwardable
+
+    def instance
+      @instance ||= Instance.new
+    end
+
+    def_delegators :instance, :configuration, :configuration=, :configure
+  end
+
+  class Instance
+    attr_accessor :configuration
+
+    def initialize
+      self.configuration = Fly::Configuration.new
+    end
+
+    def configure
+      configuration = Fly::Configuration.new
+      yield(configuration) if block_given?
+      self.configuration = configuration
+    end
+  end
+end

data/lib/fly-ruby/configuration.rb

@@ -0,0 +1,46 @@
+module Fly
+  class Configuration
+    # Set the region where this instance of the application is deployed
+    attr_accessor :current_region
+
+    # Set the region where the primary database lives, i.e "ams"
+    attr_accessor :primary_region
+
+    # Automatically replay these HTTP methods in the primary region
+    attr_accessor :replay_http_methods
+
+    # Environment variables related to the database connection.
+    # These get by this middleware in secondary regions, so they must be interpolated
+    # rather than defined directly in the configuration.
+    attr_accessor :database_url_env_var
+    attr_accessor :database_host_env_var
+    attr_accessor :database_port_env_var
+
+    # Cookie written and read by this middleware storing a UNIX timestamp.
+    # Requests arriving before this timestamp will be replayed in the primary region.
+    attr_accessor :replay_threshold_cookie
+
+    # How long, in seconds, should all requests from the same client be replayed in the
+    # primary region after a successful write replay
+    attr_accessor :replay_threshold_in_seconds
+
+    def initialize
+      self.primary_region = ENV["PRIMARY_REGION"]
+      self.current_region = ENV["FLY_REGION"]
+      self.replay_http_methods = ["POST", "PUT", "PATCH", "DELETE"]
+      self.database_url_env_var = "DATABASE_URL"
+      self.database_host_env_var = "DATABASE_HOST"
+      self.database_port_env_var = "DATABASE_PORT"
+      self.replay_threshold_cookie = "fly-replay-threshold"
+      self.replay_threshold_in_seconds = 5
+    end
+
+    def database_url
+      ENV[database_url_env_var]
+    end
+
+    def eligible_for_activation?
+      database_url && primary_region && current_region
+    end
+  end
+end

data/lib/fly-ruby/railtie.rb

@@ -0,0 +1,9 @@
+class Fly::Railtie < Rails::Railtie
+  initializer("fly.regional_database") do |app|
+    if Fly.configuration.eligible_for_activation?
+      app.config.middleware.insert_after ActionDispatch::Executor, Fly::RegionalDatabase
+    elsif !ENV["TESTING"]
+      puts "Warning: DATABASE_URL, PRIMARY_REGION and FLY_REGION must be set to activate the fly-ruby middleware. Middleware not loaded."
+    end
+  end
+end

data/lib/fly-ruby/regional_database.rb

@@ -0,0 +1,111 @@
+module Fly
+  # Note that using instance variables in Rack middleware is considered a poor practice in
+  # multithreaded environments. Instead of using dirty tricks like using Object#dup,
+  # values are passed to methods.
+
+  class RegionalDatabase
+    def initialize(app)
+      @app = app
+      prefer_regional_database! unless in_primary_region?
+    end
+
+    # Overwrite the primary database URL with that of the regional replica
+    def prefer_regional_database!
+      uri = URI.parse(Fly.configuration.database_url)
+      hostname = "#{Fly.configuration.current_region}.#{uri.hostname}"
+      port = 5433
+
+      uri.hostname = hostname
+      uri.port = port
+      uri.to_s
+
+      ENV[Fly.configuration.database_url_env_var] = uri.to_s
+      ENV[Fly.configuration.database_host_env_var] = hostname
+      ENV[Fly.configuration.database_port_env_var] = port.to_s
+    end
+
+    def in_primary_region?
+      Fly.configuration.primary_region == Fly.configuration.current_region
+    end
+
+    def regional_database_url
+    end
+
+    def response_body
+      "<html>Replaying request in #{Fly.configuration.primary_region}</html>"
+    end
+
+    # Stop the current request and ask for it to be replayed in the primary region.
+    # Pass one of three states to the target region, to determine how to handle the request:
+    #
+    # Possible states: captured_write, http_method, threshold
+    # captured_write: A write was rejected by the database
+    # http_method: A non-idempotent HTTP method was replayed before hitting the application
+    # threshold: A recent write set a threshold during which all requests are replayed
+    #
+    def replay_in_primary_region!(state:)
+      res = Rack::Response.new(
+        response_body,
+        409,
+        {"fly-replay" => "region=#{Fly.configuration.primary_region};state=#{state}"}
+      )
+      res.finish
+    end
+
+    def within_replay_threshold?(threshold)
+      threshold && (threshold.to_i - Time.now.to_i) > 0
+    end
+
+    def replayable_http_method?(http_method)
+      Fly.configuration.replay_http_methods.include?(http_method)
+    end
+
+    def replay_request_state(header_value)
+      header_value&.scan(/(.*?)=(.*?)($|;)/)&.detect { |v| v[0] == "state" }&.at(1)
+    end
+
+    def call(env)
+      request = Rack::Request.new(env)
+
+    # Check whether this request satisfies any of the following conditions for replaying in the primary region:
+    #
+    # 1. Its HTTP method matches those configured for automatic replay (post/patch/put/delete by default).
+    #    This approach should avoid potentially slow code execution - before_actions or other controller code -
+    #    happening before a request reaches a database write.
+    # 2. It arrived before the threshold defined by the last write request. This threshold
+    #    helps avoid the same client from missing its own write due to replication lag,
+    #    like when a user adds to a todo list via XHR
+
+      if !in_primary_region?
+        if replayable_http_method?(request.request_method)
+          return replay_in_primary_region!(state: "http_method")
+        elsif within_replay_threshold?(request.cookies[Fly.configuration.replay_threshold_cookie])
+          return replay_in_primary_region!(state: "threshold")
+        end
+      end
+
+      begin
+        status, headers, body = @app.call(env)
+      rescue ActiveRecord::StatementInvalid => e
+        if e.cause.is_a?(PG::ReadOnlySqlTransaction)
+          return replay_in_primary_region!(state: "captured_write")
+        else
+          raise e
+        end
+      end
+
+      response = Rack::Response.new(body, status, headers)
+      replay_state = replay_request_state(request.get_header("HTTP_FLY_REPLAY_SRC"))
+
+      # Request was replayed, but not by a threshold
+      if replay_state && replay_state != "threshold"
+        response.set_cookie(
+          Fly.configuration.replay_threshold_cookie,
+          Time.now.to_i + Fly.configuration.replay_threshold_in_seconds
+        )
+      end
+
+      response.finish
+    end
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: fly-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Joshua Sierles
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-07-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Automate the work requied to run Ruby apps against region-local databases
+  on Fly.io
+email: joshua@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/test.yml"
+- ".gitignore"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- fly-ruby.gemspec
+- lib/fly-ruby.rb
+- lib/fly-ruby/configuration.rb
+- lib/fly-ruby/railtie.rb
+- lib/fly-ruby/regional_database.rb
+homepage: https://github.com/superfly/fly-ruby
+licenses:
+- BSD-3-Clause
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: Augment Ruby web apps for deployment in Fly.io
+test_files: []