request_migrations 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03674ecf6a2120accd4fcbbbe4add7f73a94098e08882a65630085b3dcc38ecd
-  data.tar.gz: 38b32703419f8857737fc0b8fa61d5ada954f69c201247892441291b901ed0fb
+  metadata.gz: c2224934d0be51149ebf90a756ae9cfd9172ee83310609c9cfc94c49c4c75166
+  data.tar.gz: 3de2f808de4c02d7de89ec9baae0b5d68cadab94d8118e13688a941de791d3cf
 SHA512:
-  metadata.gz: ed9e6c8e9cf08938177b687496f83e58e7ecbf0a35cda2f9f84428f83acff381c882d33f53e2ba3bc51b0d533f577f7a93bc1c9fc2533a57d79bd479a80a550f
-  data.tar.gz: 36cc532f949768e70bf1582a9c652db79e5900811ebe0a4e08bd9a4840442b346c6c93cedd0d6d4c6d2d39bf6f487c321dd4d731c8f8533fa7d64ff65954dd85
+  metadata.gz: 944f3e23fe55b3d9eb56cdf0491871bfecea72a5c9a57b15f8827152b7cf5a21ab0e0ac6c1f254a9afabe4fc980562b864e96a2868ec864a314d41876e1af987
+  data.tar.gz: e3fa22992ac3aadcd34ce860310f6a496f4aa7f54179090863bcf993582e2c757fa07677862973b817edc2d209b289284e19ec040249c62011ad20ceb41ee0c6

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.0.1
+
+- Fix application order of `request` migrations.
+
 ## 1.0.0
 
 - Initial release.

data/README.md

@@ -3,12 +3,17 @@
 [![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.
+backwards-compatible migrations for API requests, responses, and more. Read [the blog
+post](https://keygen.sh/blog/breaking-things-without-breaking-things/).
+
+This gem was extracted from [Keygen](https://keygen.sh) and is being used in production
+to serve millions of API requests per day.
+
+![request_migrations diagram](https://user-images.githubusercontent.com/6979737/175964358-a2d8951d-46c6-4962-9f5e-0569cbf5972e.png)
 
 Sponsored by:
 
-[![Keygen logo](https://camo.githubusercontent.com/d50a6bd1f31fd4da523b8aa555a54356cc2d3e81eb8bc9123303787e44c5bb07/68747470733a2f2f6b657967656e2e73682f696d616765732f62616467652e706e67)](https://keygen.sh)
+[![Keygen logo](https://user-images.githubusercontent.com/6979737/175406169-bd8bf064-7343-4bd1-94b7-a773ecec07b8.png)](https://keygen.sh)
 
 _A software licensing and distribution API built for developers._
 
@@ -47,7 +52,7 @@ _We're working on improving the docs._
 
 - Define migrations for migrating a response between versions.
 - Define migrations for migrating a request between versions.
-- Define migrations for applying one-off migrations.
+- Define migrations for applying data migrations.
 - Define version-based routing constraints.
 - It's fast.
 
@@ -127,7 +132,7 @@ Next, we'll need to configure `request_migrations` via an initializer under
 
 ```ruby
 RequestMigrations.configure do |config|
-  # Define a resolver to determine the current version. Here, you can perform
+  # Define a resolver to determine the target 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 {
@@ -186,7 +191,12 @@ 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.
+should be applied. An `ActionDispatch::Response` will be yielded, the
+current response (calls `controller#response`).
+
+The gem makes no assumption on a response's content type or what the migration
+will do. You could, for example, migrate the response body, or mutate the
+headers, or even change the response's status code.
 
 ### Request migrations
 
@@ -206,19 +216,25 @@ 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.
+should be applied. An `ActionDispatch::Request` object will be yielded,
+the current request (calls `controller#request`).
+
+Again, like with response migrations, the gem makes no assumption on what
+a migration does. A migration could mutate a request's params, or mutate
+headers. It's up to you, all it does is provide the request.
 
-### One-off migrations
+Request migrations should [avoid using the `migrate` method](#avoid-migrate-for-request-migrations).
+
+### Data 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`.
+Well, it comes down to support for data 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
@@ -248,7 +264,7 @@ 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
+that we also needed to apply these migrations to? Well, we can use a data migration
 here, via the `Migrator` class:
 
 ```ruby
@@ -274,17 +290,19 @@ class WebhookWorker
 end
 ```
 
-Now, we've successfully applied a migration to both our API responses, as well
+This will apply the block defined in `migrate` onto our data. With that,
+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.
 
-In addition to one-off migrations, this allows for easier testing.
+In addition to data migrations, this allows for easier testing.
 
 ### 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.
+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
@@ -302,13 +320,13 @@ Rails.application.routes.draw do
 end
 ```
 
-Currently, routing constraints only work for the `:semver` version format.
+Currently, routing constraints only work for the `:semver` version format. (PRs welcome!)
 
 ### Configuration
 
 ```ruby
 RequestMigrations.configure do |config|
-  # Define a resolver to determine the current version. Here, you can perform
+  # Define a resolver to determine the target 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 {
@@ -345,17 +363,19 @@ end
 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`.        |
+| 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`.         |
+
+All versions will be sorted according to the format's type.
 
 ## Testing
 
-Using one-offs allows for easier testing of migrations. For example, using Rspec:
+Using data migrations allows for easier testing of migrations. For example, using Rspec:
 
 ```ruby
 describe CombineNamesForUserMigration do
@@ -385,9 +405,24 @@ describe CombineNamesForUserMigration do
 end
 ```
 
+To avoid polluting the global configuration, you can use `RequestMigrations::Testing`
+within your application's `spec/rails_helper.rb` (or similar).
+
+```ruby
+Rspec.configure do |config|
+  config.before :each do
+    RequestMigrations::Testing.setup!
+  end
+
+  config.after :each do
+    RequestMigrations::Testing.teardown!
+  end
+end
+```
+
 ## Tips and tricks
 
-Over the years, we're learned a thing or two about writing request migrations. We'll share tips here.
+Over the years, we're learned a thing or two about versioning an API. We'll share tips here.
 
 ### Use pattern matching
 
@@ -539,12 +574,36 @@ class V1x0::UsersController
 end
 ```
 
+### Avoid migrate for request migrations
+
+Avoid using `migrate` for request migrations. If you do, then data migrations, e.g. for
+webhooks, will attempt to apply the request migrations. This may erroneously produce bad
+output, or even undo a response migration. Instead, keep all request migration logic,
+e.g. transforming params, inside of the `request` block.
+
+```ruby
+class SomeMigration < RequestMigrations::Migration
+  # Bad (side-effects for data migrations)
+  migrate do |params|
+    params[:foo] = params.delete(:bar)
+  end
+
+  request do |req|
+    migrate!(req.params)
+  end
+
+  # Good
+  request do |req|
+    req.params[:foo] = req.params.delete(:bar)
+  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.
+during upgrades. Consider only making _additive_ changes. Instead, consider removing or
+hiding the documenation for old or deprecated endpoints, to limit any new usage.
 
 ```ruby
 Rails.application.routes.draw do
@@ -564,7 +623,7 @@ end
 
 ### Avoid n+1s
 
-Avoid introducing n+1 queries in your migration. Try to utilize the current data you have
+Avoid introducing n+1 queries in your migrations. Try to utilize the current data you have
 to perform more meaningful queries, returning only the data needed for the migration.
 
 ```ruby
@@ -615,7 +674,7 @@ end
 ```
 
 Instead of potentially tens or hundreds of queries, we make a single purposeful query
-to get the data we need to complete the migration.
+to get the data we need in order to complete the migration.
 
 ---
 

data/lib/request_migrations/configuration.rb

@@ -26,13 +26,13 @@ module RequestMigrations
     ##
     # current_version defines the latest version.
     #
-    # @return [String, Integer, Float] the current version.
+    # @return [String, Integer, Float, nil] the current version.
     config_accessor(:current_version) { nil }
 
     ##
     # versions defines past versions and their migrations.
     #
-    # @return [Hash<String, Array<String, Integer, Float>>] past versions.
-    config_accessor(:versions) { [] }
+    # @return [Hash<String, Array<Symbol, String, Class>>] past versions.
+    config_accessor(:versions) { {} }
   end
 end

data/lib/request_migrations/controller.rb

@@ -15,7 +15,7 @@ module RequestMigrations
       def migrate!
         logger.debug { "Migrating from #{current_version} to #{target_version} (#{migrations.size} potential migrations)" }
 
-        migrations.each_with_index { |migration, i|
+        migrations.reverse.each_with_index { |migration, i|
           logger.debug { "Applying migration #{migration} (#{i + 1}/#{migrations.size})" }
 
           migration.new.migrate_request!(request)

data/lib/request_migrations/gem.rb

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

data/lib/request_migrations/migration.rb

@@ -1,6 +1,29 @@
 # frozen_string_literal: true
 
 module RequestMigrations
+  ##
+  # Migration represents a migration for a specific version.
+  #
+  # @example
+  #   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
   class Migration
     ##
     # @private
@@ -54,7 +77,7 @@ module RequestMigrations
       #
       # @param if [Proc] the proc which determines if the migration should run.
       #
-      # @yield [request] the block containing the migration.
+      # @yield [ActionDispatch::Request] the current request.
       def request(if: nil, &block)
         self.request_blocks << ConditionalBlock.new(if:, &block)
       end
@@ -64,7 +87,7 @@ module RequestMigrations
       #
       # @param if [Proc] the proc which determines if the migration should run.
       #
-      # @yield [data] the block containing the migration.
+      # @yield [Any] the provided data.
       def migrate(if: nil, &block)
         self.migration_blocks << ConditionalBlock.new(if:, &block)
       end
@@ -74,7 +97,7 @@ module RequestMigrations
       #
       # @param if [Proc] the proc which determines if the migration should run.
       #
-      # @yield [response] the block containing the migration.
+      # @yield [ActionDispatch::Response] the current response.
       def response(if: nil, &block)
         self.response_blocks << ConditionalBlock.new(if:, &block)
       end

data/lib/request_migrations/migrator.rb

@@ -15,9 +15,9 @@ module RequestMigrations
     ##
     # migrate! attempts to apply all matching migrations on data.
     #
-    # @param data [*] the data to be migrated.
+    # @param data [Any] the data to be migrated.
     #
-    # @return [*] the migrated data.
+    # @return [void]
     def migrate!(data:)
       logger.debug { "Migrating from #{current_version} to #{target_version} (#{migrations.size} potential migrations)" }
 
@@ -37,11 +37,12 @@ module RequestMigrations
 
     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) }
+          .sort
+          .reverse
           .flat_map { |(_, migrations)| migrations }
           .map { |migration|
             case migration

data/lib/request_migrations/railtie.rb

@@ -1,4 +1,6 @@
 module RequestMigrations
+  ##
+  # @private
   class Railtie < ::Rails::Railtie
     ActionDispatch::Routing::Mapper.send(:include, Router::Constraints)
   end

data/lib/request_migrations/testing.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RequestMigrations
+  class Testing
+    @@config = RequestMigrations::Configuration.new
+
+    ##
+    # setup! stores the original config and replaces it with a clone for testing.
+    def self.setup!
+      @@config = RequestMigrations.config
+
+      RequestMigrations.reset!
+      RequestMigrations.configure do |config|
+        @@config.config.each { |(k, v)| config.config[k] = v }
+      end
+    end
+
+    ##
+    # teardown! restores the original config.
+    def self.teardown!
+      RequestMigrations.config = @@config
+    end
+  end
+end

data/lib/request_migrations.rb

@@ -43,6 +43,18 @@ module RequestMigrations
   # config returns the current config.
   def self.config = @config ||= Configuration.new
 
+  ##
+  # @private
+  def self.config=(cfg)
+    @config = cfg
+  end
+
+  ##
+  # @private
+  def self.reset!
+    @config = RequestMigrations::Configuration.new
+  end
+
   ##
   # logger returns the configured logger.
   #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: request_migrations
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Zeke Gabrielse
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-06-23 00:00:00.000000000 Z
+date: 2022-07-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -74,6 +74,7 @@ files:
 - lib/request_migrations/migrator.rb
 - lib/request_migrations/railtie.rb
 - lib/request_migrations/router.rb
+- lib/request_migrations/testing.rb
 - lib/request_migrations/version.rb
 homepage: https://github.com/keygen-sh/request_migrations
 licenses: