request_migrations 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a07f06f1ea7b2b51851ff1490e1233363bc4d13bc6ac8918e7c1d886c9497ffd
+  data.tar.gz: 79f9bb8c317e906b4d4d6992811156103265d902f82ca0fcc1ac65a6e85327de
+SHA512:
+  metadata.gz: 595d53c2b5d25dd34d4212e9db9208b96dccf684ec03e4cd75fa485d5421c400cc0b465e4914d7613a3ef15c08757b93ce163cebf1cb886dccf14e7986ca16bb
+  data.tar.gz: 95cd329eee002333f976886c2394a538dc1f3e6231f093a4d7155b9330eaf0725dc9ed38e31c6ccc0d9e7fdeb6a32b7f54970dc6114064b6286b96888b0be4d2

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Test release.

data/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+## Security issues
+
+If you have found a security related issue, please do not file an issue on
+GitHub or send a PR addressing the issue. Contact [Keygen](mailto:security@keygen.sh)
+directly. You will be given public credit for your disclosure.
+
+## Reporting issues
+
+Please try to answer the following questions in your bug report:
+
+- What did you do?
+- What did you expect to happen?
+- What happened instead?
+
+Make sure to include as much relevant information as possible. Ruby version,
+Rails version, `request_migrations` version, OS version and any stack traces
+you have are very valuable.
+
+## Pull Requests
+
+- **Add tests!** Your patch won't be accepted if it doesn't have tests.
+
+- **Document any change in behaviour**. Make sure the README and any other
+  relevant documentation are kept up-to-date.
+
+- **Create topic branches**. Please don't ask us to pull from your master branch.
+
+- **One pull request per feature**. If you want to do more than one thing, send
+  multiple pull requests.
+
+- **Send coherent history**. Make sure each individual commit in your pull
+  request is meaningful. If you had to make multiple intermediate commits while
+  developing, please squash them before sending them to us.

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2022 Keygen LLC
+
+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/README.md

@@ -0,0 +1,540 @@
+# request_migrations
+
+[![Gem Version](https://badge.fury.io/rb/request_migrations.svg)](https://badge.fury.io/rb/request_migrations)
+
+**Make breaking API changes without breaking things!** Use `request_migrations` to craft
+backwards-compatible migrations for API requests, responses, and more. This is being
+used in production by [Keygen](https://keygen.sh) to serve millions of API requests per day.
+
+Sponsored by:
+
+[![Keygen logo](https://camo.githubusercontent.com/d50a6bd1f31fd4da523b8aa555a54356cc2d3e81eb8bc9123303787e44c5bb07/68747470733a2f2f6b657967656e2e73682f696d616765732f62616467652e706e67)](https://keygen.sh)
+
+_A software licensing and distribution API built for developers._
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'request_migrations'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install request_migrations
+```
+
+## Supported Rubies
+
+`request_migrations` supports Ruby 3. We encourage you to upgrade if you're on an older
+version. Ruby 3 provides a lot of great features, like better pattern matching.
+
+## Documentation
+
+You can find the documentation on [RubyDoc](https://rubydoc.info/github/keygen-sh/request_migrations).
+
+_We're working on improving the docs._
+
+## Features
+
+- Define migrations for migrating a response between versions.
+- Define migrations for migrating a request between versions.
+- Define migrations for applying one-off migrations.
+- Define version-based routing constraints.
+
+## Usage
+
+Use `request_migrations` to make _backwards-incompatible_ changes in your code, while
+providing a _backwards-compatible_ interface for clients on older API versions. What
+exactly does that mean? Well, let's demonstrate!
+
+Let's assume that we provide an API service, which has `/users` CRUD resources.
+
+Let's also assume we start with the following `User` model:
+
+```ruby
+class User
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+
+  attribute :name, :string
+end
+```
+
+After awhile, we realize our `User` model's combined `name` attribute is not working too
+well, and we want to change it to `first_name` and `last_name`.
+
+So we write a database migration that changes our `User` model:
+
+```ruby
+class User
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+
+  attribute :first_name, :string
+  attribute :last_name, :string
+end
+```
+
+But what about the API consumers who were relying on `name`? We just broke our API contract
+with them! To resolve this, let's create our first request migration.
+
+We recommend that migrations be stored under `app/migrations/`.
+
+```ruby
+class CombineNamesForUserMigration < RequestMigrations::Migration
+  # Provide a useful description of the change
+  description %(transforms a user's first and last name to a combined name attribute)
+
+  # Migrate inputs that contain a user. The migration should mutate
+  # the input, whatever that may be.
+  migrate if: -> data { data in type: 'user' } do |data|
+    first_name = data.delete(:first_name)
+    last_name  = data.delete(:last_name)
+
+    data[:name] = "#{first_name} #{last_name}"
+  end
+
+  # Migrate the response. This is where you provide the migration input.
+  response if: -> res { res.successful? && res.request.params in controller: 'api/v1/users',
+                                                                 action: 'show' } do |res|
+    data = JSON.parse(res.body, symbolize_names: true)
+
+    # Call our migrate definition above
+    migrate!(data)
+
+    res.body = JSON.generate(data)
+  end
+end
+```
+
+As you can see, with pattern matching, it makes creating migrations for certain
+resources simple. Here, we've defined a migration that only runs for the `users#show`
+and `me#show` resources, and only when the response is successfuly. In addition,
+the data is only migrated when the response body contains a user.
+
+Next, we'll need to configure `request_migrations` via an initializer under
+`initializers/request_migrations.rb`:
+
+```ruby
+RequestMigrations.configure do |config|
+  # Define a resolver to determine the current version. Here, you can perform
+  # a lookup on the current user using request parameters, or simply use
+  # a header like we are here, defaulting to the latest version.
+  config.request_version_resolver = -> request {
+    request.headers.fetch('Foo-Version') { config.current_version }
+  }
+
+  # Define the latest version of our application.
+  config.current_version = '1.1'
+
+  # Define previous versions and their migrations, in descending order.
+  config.versions = {
+    '1.0' => %i[combine_user_names_migration],
+  }
+end
+```
+
+Lastly, you'll want to update your application controller so that migrations
+are applied:
+
+```ruby
+class ApplicationController < ActionController::API
+  include RequestMigrations::Controller::Migrations
+end
+```
+
+Now, when an API client provides a `Foo-Version: 1.0` header, they'll receive a
+response containing the combined `name` attribute.
+
+### Response migrations
+
+We covered this above, but response migrations define a change to a response.
+You define a response migration by using the `response` class method.
+
+```ruby
+class RemoveVowelsMigration < RequestMigrations::Migration
+  description %(in the past, we had a bug that removed all vowels, and some clients rely on that behavior)
+
+  response if: -> res { res.request.params in action: 'index' | 'show' | 'create' | 'update' } do |res|
+    body = JSON.parse(res.body, symbolize_names: true)
+
+    # Mutate the response body by removing all vowels
+    body.deep_transform_values! { _1.gsub(/[aeiou]/, '') }
+
+    res.body = JSON.generate(body)
+  end
+end
+```
+
+The `response` method accepts an `:if` keyword, which should be a lambda
+that evaluates to a boolean, which determines whether or not the migration
+should be applied.
+
+### Request migrations
+
+Request migrations define a change on a request. For example, modifying a request's
+headers. You define a response migration by using the `request` class method.
+
+```ruby
+class AssumeContentTypeMigration < RequestMigrations::Migration
+  description %(in the past, we assumed all requests were JSON, but that has since changed)
+
+  # Migrate the request, adding an assumed content type to all requests.
+  request do |req|
+    req.headers['Content-Type'] = 'application/json'
+  end
+end
+```
+
+The `request` method accepts an `:if` keyword, which should be a lambda
+that evaluates to a boolean, which determines whether or not the migration
+should be applied.
+
+### One-off migrations
+
+In our first scenario, where we combined our user's name attributes, we defined
+our migration using the `migrate` class method. At this point, you may be wondering
+why we did that, since we didn't use that method for the 2 previous request and
+response migrations above.
+
+Well, it comes down to support for one-off migrations (as well as offering
+a nice interface for pattern matching inputs).
+
+Let's go back to our first example, `CombineNamesForUserMigration`.
+
+```ruby
+class CombineNamesForUserMigration < RequestMigrations::Migration
+  # Provide a useful description of the change
+  description %(transforms a user's first and last name to a combined name attribute)
+
+  # Migrate inputs that contain a user. The migration should mutate
+  # the input, whatever that may be.
+  migrate if: -> data { data in type: 'user' } do |data|
+    first_name = data.delete(:first_name)
+    last_name  = data.delete(:last_name)
+
+    data[:name] = "#{first_name} #{last_name}"
+  end
+
+  # Migrate the response. This is where you provide the migration input.
+  response if: -> res { res.successful? && res.request.params in controller: 'api/v1/users' | 'api/v1/me',
+                                                                 action: 'show' } do |res|
+    data = JSON.parse(res.body, symbolize_names: true)
+
+    # Call our migrate definition above
+    migrate!(data)
+
+    res.body = JSON.generate(data)
+  end
+end
+```
+
+What if we had [a webhook system](https://keygen.sh/blog/how-to-build-a-webhook-system-in-rails-using-sidekiq/)
+that we also needed to apply these migrations to? Well, we can use a one-off migration
+here, via the `Migrator` class:
+
+```ruby
+class WebhookWorker
+  def perform(event, endpoint, data)
+    # ...
+
+    # Migrate event data from latest version to endpoint's configured version
+    current_version = RequestMigrations.config.current_version
+    target_version  = endpoint.api_version
+    migrator        = RequestMigrations::Migrator.new(
+      from: current_version,
+      to: target_version,
+    )
+
+    # Migrate the event data (tries to apply all matching migrations)
+    migrator.migrate!(data:)
+
+    # ...
+
+    event.send!(data)
+  end
+end
+```
+
+Now, we've successfully applied a migration to both our API responses, as well
+as to the webhook events we send. In this case, if our `event` matches the
+our user shape, e.g. `type: 'user'`, then the migration will be applied.
+
+### Routing constraints
+
+When you want to encourage API clients to upgrade, you can utilize a routing `version_constraint`
+to define routes only available for certain versions. You can also utilize routing constraints
+to remove an API endpoint entirely.
+
+```ruby
+Rails.application.routes.draw do
+  # This endpoint is only available for version 1.1 and above
+  version_constraint '>= 1.1' do
+    resources :some_shiny_new_resource
+  end
+
+  # Remove this endpoint for any version below 1.1
+  version_constraint '< 1.1' do
+    scope module: :v1x0 do
+      resources :a_deprecated_resource
+    end
+  end
+end
+```
+
+Currently, routing constraints only work for the `:semver` version format.
+
+### Configuration
+
+```ruby
+RequestMigrations.configure do |config|
+  # Define a resolver to determine the current version. Here, you can perform
+  # a lookup on the current user using request parameters, or simply use
+  # a header like we are here, defaulting to the latest version.
+  config.request_version_resolver = -> request {
+    request.headers.fetch('Foo-Version') { config.current_version }
+  }
+
+  # Define the accepted version format. Default is :semver.
+  config.version_format = :semver
+
+  # Define the latest version of our application.
+  config.current_version = '1.2'
+
+  # Define previous versions and their migrations, in descending order.
+  # Should be a hash, where the key is the version and the value is an
+  # array of migration symbols or classes.
+  config.versions = {
+    '1.1' => %i[
+      has_one_author_to_has_many_for_posts_migration
+      has_one_author_to_has_many_for_post_migration
+    ],
+    '1.0' => %i[
+      combine_names_for_users_migration
+      combine_names_for_user_migration
+    ],
+  }
+
+  # Use a custom logger. Must be a tagged logger. Defaults to
+  # using Rails.logger.
+  config.logger = ActiveSupport::TaggedLogging.new(...)
+end
+```
+
+### Version formats
+
+By default, `request_migrations` uses a `:semver` version format, but it can be configured
+to instead use one of the following, set via `config.version_format=`.
+
+| Format     |                                                     |
+|:-----------|:----------------------------------------------------|
+| `:semver`  | Use semantic versions, e.g. `1.0`, `1.1, and `2.0`. |
+| `:date`    | Use date versions, e.g. `2020-09-02`, `2021-01-01`. |
+| `:integer` | Use integer versions, e.g. `1`, `2`, and `3`.       |
+| `:float`   | Use float versions, e.g. `1.0`, `1.1`, and `2.0`.   |
+| `:string`  | Use string versions, e.g. `a`, `b`, and `z`.        |
+
+### Tips and tricks
+
+Over the years, we're learned a thing or two about writing request migrations. We'll share tips here.
+
+#### Use pattern matching
+
+Pattern matching really cleans up the `:if` conditions, and overall makes migrations more readable.
+
+```ruby
+class AddUsernameAttributeToUsersMigration < RequestMigrations::Migration
+  description %(adds username attributes to a collection of users)
+
+  migrate if: -> body { body in data: [*] } do |body|
+    case body
+    in data: [*, { type: 'users', attributes: { ** } }, *]
+      body[:data].each do |user|
+        case user
+        in type: 'users', attributes: { email: }
+          user[:attributes][:username] = email
+        else
+        end
+      end
+    else
+    end
+  end
+
+  response if: -> res { res.successful? && res.request.params in controller: 'api/v1/users',
+                                                                 action: 'index' } do |res|
+    body = JSON.parse(res.body, symbolize_names: true)
+
+    migrate!(body)
+
+    res.body = JSON.generate(body)
+  end
+end
+```
+
+Just be sure to remember your `else` block when `case` pattern matching. :)
+
+#### Route helpers
+
+If you need to use route helpers in a migration, include them in your migration:
+
+```ruby
+class SomeMigration < RequestMigrations::Migration
+  include Rails.application.routes.url_helpers
+end
+```
+
+#### Separate by shape
+
+Define separate migrations for different input shapes, e.g. define a migration for an `#index`
+to migrate an array of objects, and define another migration that handles the singular object
+from `#show`, `#create` and `#update`. This will help keep your migrations readable.
+
+For example, for a singular user response:
+
+```ruby
+class CombineNamesForUserMigration < RequestMigrations::Migration
+  description %(transforms a user's first and last name to a combined name attribute)
+
+  migrate if: -> data { data in type: 'user' } do |data|
+    first_name = data.delete(:first_name)
+    last_name  = data.delete(:last_name)
+
+    data[:name] = "#{first_name} #{last_name}"
+  end
+
+  response if: -> res { res.successful? && res.request.params in controller: 'api/v1/users',
+                                                                 action: 'show' } do |res|
+    data = JSON.parse(res.body, symbolize_names: true)
+
+    migrate!(data)
+
+    res.body = JSON.generate(data)
+  end
+end
+```
+
+And for a response containing a collection of users:
+
+```ruby
+class CombineNamesForUserMigration < RequestMigrations::Migration
+  description %(transforms a collection of users' first and last names to a combined name attribute)
+
+  migrate if: -> data { data in [*, { type: 'user' }, *] do |data|
+    data.each do |record|
+      case record
+      in type: 'user', first_name:, last_name:
+        record[:name] = "#{first_name} #{last_name}"
+
+        record.delete(:first_name)
+        record.delete(:last_name)
+      else
+      end
+    end
+  end
+
+  response if: -> res { res.successful? && res.request.params in controller: 'api/v1/users',
+                                                                 action: 'index' } do |res|
+    data = JSON.parse(res.body, symbolize_names: true)
+
+    migrate!(data)
+
+    res.body = JSON.generate(data)
+  end
+end
+```
+
+Note that the `migrate` method now migrates an array input, and matches on the `#index` route.
+
+#### Always check response status
+
+Always check a response's status. You don't want to unintentionally apply migrations to error
+responses.
+
+```ruby
+class SomeMigration < RequestMigrations::Migration
+  response if: -> res { res.successful? } do |res|
+    # ...
+  end
+end
+```
+
+#### Don't match on URL pattern
+
+Don't match on URL pattern. Instead, use `response.request.params` to access the request params
+in a `response` migration, and use the `:controller` and `:action` params to determine route.
+
+```ruby
+class SomeMigration < RequestMigrations::Migration
+  # Bad
+  response if: -> res { res.request.path.matches?(/^\/v1\/posts$/) }
+
+  # Good
+  response if: -> res { res.request.params in controller: 'api/v1/posts', action: 'index' }
+end
+```
+
+#### Namespace deprecated controllers
+
+When you need to entirely change a controller or service class, use a `V1x0::UsersController`-style
+namespace to keep the old deprecated classes tidy.
+
+```ruby
+class V1x0::UsersController
+  def foo
+    # Some old foo action
+  end
+end
+```
+
+
+#### Avoid routing contraints
+
+Avoid using routing version constraints that remove functionality. They can be a headache
+during upgrades. Consider only making _additive_ changes. You should remove docs for old
+or deprecated endpoints to limit any new usage.
+
+```ruby
+Rails.application.routes.draw do
+  resources :users do
+    # Iffy
+    version_constraint '< 1.1' do
+      resources :posts
+    end
+
+    # Good
+    scope module: :v1x0 do
+      resources :posts
+    end
+  end
+end
+```
+
+---
+
+Have a tip of your own? Open a pull request!
+
+## Is it any good?
+
+Yes.
+
+## Credits
+
+Credit goes to Stripe for inspiring the [high-level migration strategy](https://stripe.com/blog/api-versioning).
+Intercom has [another good post on the topic](https://www.intercom.com/blog/api-versioning/).
+
+## Contributing
+
+If you have an idea, or have discovered a bug, please open an issue or create a pull request.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/SECURITY.md

@@ -0,0 +1,7 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you find a vulnerability in `request_migrations`, please contact Keygen via
+[email](mailto:security@keygen.sh). You will be given public credit for your
+disclosure.

data/lib/request_migrations/configuration.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RequestMigrations
+  class Configuration
+    include ActiveSupport::Configurable
+
+    config_accessor(:logger)                   { Rails.logger }
+    config_accessor(:request_version_resolver) { -> req { self.current_version } }
+    config_accessor(:version_format)           { :semver }
+    config_accessor(:current_version)          { nil }
+    config_accessor(:versions)                 { [] }
+  end
+end

data/lib/request_migrations/controller.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module RequestMigrations
+  module Controller
+    class Migrator < Migrator
+      def initialize(request:, response:, **kwargs)
+        super(**kwargs)
+
+        @request  = request
+        @response = response
+      end
+
+      def migrate!
+        logger.debug { "Migrating from #{current_version} to #{target_version} (#{migrations.size} potential migrations)" }
+
+        migrations.each_with_index { |migration, i|
+          logger.debug { "Applying migration #{migration} (#{i + 1}/#{migrations.size})" }
+
+          migration.new.migrate_request!(request)
+        }
+
+        yield
+
+        migrations.each_with_index { |migration, i|
+          logger.debug { "Applying migration #{migration} (#{i + 1}/#{migrations.size})" }
+
+          migration.new.migrate_response!(response)
+        }
+
+        logger.debug { "Migrated from #{current_version} to #{target_version}" }
+      end
+
+      private
+
+      attr_accessor :request,
+                    :response
+
+      def logger = RequestMigrations.logger.tagged(request&.request_id)
+    end
+
+    module Migrations
+      extend ActiveSupport::Concern
+
+      included do
+        around_action :apply_migrations!
+
+        private
+
+        def apply_migrations!
+          current_version = RequestMigrations.config.current_version
+          target_version  = RequestMigrations.config.request_version_resolver.call(request)
+
+          migrator = Migrator.new(from: current_version, to: target_version, request:, response:)
+          migrator.migrate! { yield }
+        end
+      end
+    end
+
+    module Constraints
+      extend ActiveSupport::Concern
+
+      included do
+        # TODO(ezekg) Implement controller-level version constraints
+      end
+    end
+  end
+end

data/lib/request_migrations/gem.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RequestMigrations
+  VERSION = "0.1.0"
+end

data/lib/request_migrations/migration.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module RequestMigrations
+  class Migration
+    class ConditionalBlock
+      def initialize(if: nil, &block)
+        @if    = binding.local_variable_get(:if)
+        @block = block
+      end
+
+      def call(ctx, *args)
+        return if
+          @if.respond_to?(:call) && !@if.call(*args)
+
+        ctx.instance_exec(*args, &@block)
+      end
+    end
+
+    module DSL
+      def self.extended(klass)
+        class << klass
+          attr_accessor :description_value,
+                        :changeset_value,
+                        :request_blocks,
+                        :migration_blocks,
+                        :response_blocks
+        end
+
+        klass.description_value = nil
+        klass.request_blocks    = []
+        klass.migration_blocks  = []
+        klass.response_blocks   = []
+      end
+
+      def inherited(klass)
+        klass.description_value = description_value.dup
+        klass.request_blocks    = request_blocks.dup
+        klass.migration_blocks  = migration_blocks.dup
+        klass.response_blocks   = response_blocks.dup
+      end
+
+      def description(desc)
+        self.description_value = desc
+      end
+
+      def request(if: nil, &block)
+        self.request_blocks << ConditionalBlock.new(if:, &block)
+      end
+
+      def migrate(if: nil, &block)
+        self.migration_blocks << ConditionalBlock.new(if:, &block)
+      end
+
+      def response(if: nil, &block)
+        self.response_blocks << ConditionalBlock.new(if:, &block)
+      end
+    end
+
+    extend DSL
+
+    def migrate_request!(request)
+      self.class.request_blocks.each { |block|
+        instance_exec(request) { block.call(self, _1) }
+      }
+    end
+
+    def migrate!(data)
+      self.class.migration_blocks.each { |block|
+        instance_exec(data) { block.call(self, _1) }
+      }
+    end
+
+    def migrate_response!(response)
+      self.class.response_blocks.each { |block|
+        instance_exec(response) { block.call(self, _1) }
+      }
+    end
+  end
+end

data/lib/request_migrations/migrator.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RequestMigrations
+  class Migrator
+    def initialize(from:, to:)
+      @current_version = Version.new(from)
+      @target_version  = Version.new(to)
+    end
+
+    def migrate!(data:)
+      logger.debug { "Migrating from #{current_version} to #{target_version} (#{migrations.size} potential migrations)" }
+
+      migrations.each_with_index { |migration, i|
+        logger.debug { "Applying migration #{migration} (#{i + 1}/#{migrations.size})" }
+
+        migration.new.migrate!(data)
+      }
+
+      logger.debug { "Migrated from #{current_version} to #{target_version}" }
+    end
+
+    private
+
+    attr_accessor :current_version,
+                  :target_version
+
+    def logger = RequestMigrations.logger
+
+    # TODO(ezekg) These should be sorted
+    def migrations
+      @migrations ||=
+        RequestMigrations.config.versions
+          .filter { |(version, _)| Version.new(version).between?(target_version, current_version) }
+          .flat_map { |(_, migrations)| migrations }
+          .map { |migration|
+            case migration
+            when Symbol
+              migration.to_s.classify.constantize
+            when String
+              migration.classify.constantize
+            when Class
+              migration
+            else
+              raise UnsupportedMigrationError, "migration type is unsupported: #{migration}"
+            end
+          }
+    end
+  end
+end

data/lib/request_migrations/railtie.rb

@@ -0,0 +1,5 @@
+module RequestMigrations
+  class Railtie < ::Rails::Railtie
+    ActionDispatch::Routing::Mapper.send(:include, Router::Constraints)
+  end
+end

data/lib/request_migrations/router.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RequestMigrations
+  module Router
+    module Constraints
+      class VersionConstraint
+        def initialize(constraint:)
+          @constraint = Version::Constraint.new(constraint)
+        end
+
+        def matches?(request)
+          version = Version.coerce(resolver.call(request))
+
+          @constraint.satisfies?(version)
+        end
+
+        private
+
+        def resolver = RequestMigrations.config.request_version_resolver
+      end
+
+      def version_constraint(constraint, &)
+        constraints VersionConstraint.new(constraint:) do
+          instance_eval(&)
+        end
+      end
+    end
+  end
+end

data/lib/request_migrations/version.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RequestMigrations
+  class Version
+    include Comparable
+
+    attr_reader :format,
+                :value
+
+    def initialize(version)
+      raise UnsupportedVersionError, "version is unsupported: #{version}" unless
+        version.in?(RequestMigrations.supported_versions)
+
+      @format = RequestMigrations.config.version_format.to_sym
+      @value  = case @format
+                when :semver
+                  Semverse::Version.coerce(version)
+                when :date
+                  Date.parse(version)
+                when :integer
+                  version.to_i
+                when :float
+                  version.to_f
+                when :string
+                  version.to_s
+                else
+                  raise InvalidVersionFormatError, "invalid version format: #{@format} (must be one of: #{SUPPORTED_VERSION_FORMATS.join(',')}"
+                end
+    rescue Semverse::InvalidVersionFormat,
+           Date::Error
+      raise InvalidVersionError, "invalid #{@format} version given: #{version}"
+    end
+
+    def <=>(other) = @value <=> Version.coerce(other).value
+    def to_s       = @value.to_s
+
+    class << self
+      def coerce(version)
+        version.is_a?(self) ? version : new(version)
+      end
+    end
+
+    class Constraint
+      attr_reader :format,
+                  :value
+
+      def initialize(constraint)
+        @format     = RequestMigrations.config.version_format.to_sym
+        @constraint = case @format
+                      when :semver
+                        Semverse::Constraint.coerce(constraint)
+                      when :date,
+                           :integer,
+                           :float,
+                           :string
+                        raise NotImplementedError, "#{@format} constraints are not supported"
+                      else
+                        raise InvalidVersionFormatError, "invalid version constraint format: #{@format} (must be one of: #{SUPPORTED_VERSION_FORMATS.join(',')}"
+                      end
+      end
+
+      def satisfies?(other) = @constraint.satisfies?(other)
+    end
+  end
+end

data/lib/request_migrations.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "semverse"
+require "request_migrations/gem"
+require "request_migrations/configuration"
+require "request_migrations/version"
+require "request_migrations/migration"
+require "request_migrations/migrator"
+require "request_migrations/controller"
+require "request_migrations/router"
+require "request_migrations/railtie"
+
+module RequestMigrations
+  class UnsupportedMigrationError < StandardError; end
+  class InvalidVersionFormatError < StandardError; end
+  class UnsupportedVersionError < StandardError; end
+  class InvalidVersionError < StandardError; end
+
+  SUPPORTED_VERSION_FORMATS = %i[semver date float integer string].freeze
+
+  def self.logger = @logger ||= RequestMigrations.config.logger.tagged(:request_migrations)
+  def self.config = @config ||= Configuration.new
+
+  def self.configure
+    yield config
+  end
+
+  def self.supported_versions
+    [RequestMigrations.config.current_version, *RequestMigrations.config.versions.keys].uniq.freeze
+  end
+end
+

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: request_migrations
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Zeke Gabrielse
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-06-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: semverse
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-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'
+description: Make breaking API changes without breaking things by using request_migrations
+  to craft backwards-compatible migrations for API requests, responses, and more.
+  Inspired by Stripe's API versioning strategy.
+email:
+- oss@keygen.sh
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- SECURITY.md
+- lib/request_migrations.rb
+- lib/request_migrations/configuration.rb
+- lib/request_migrations/controller.rb
+- lib/request_migrations/gem.rb
+- lib/request_migrations/migration.rb
+- lib/request_migrations/migrator.rb
+- lib/request_migrations/railtie.rb
+- lib/request_migrations/router.rb
+- lib/request_migrations/version.rb
+homepage: https://github.com/keygen-sh/request_migrations
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+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.3.7
+signing_key:
+specification_version: 4
+summary: Write request and response migrations for your Ruby on Rails API.
+test_files: []