request_migrations 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03674ecf6a2120accd4fcbbbe4add7f73a94098e08882a65630085b3dcc38ecd
-  data.tar.gz: 38b32703419f8857737fc0b8fa61d5ada954f69c201247892441291b901ed0fb
+  metadata.gz: f9ade55e7b503c08190a46b58d68dfc35f619c9cf949c12ef98e7cb58548d2b6
+  data.tar.gz: 0e2a334989b6d79ec9296e9ef3c5866b42c0121e87cc2d9fa219835ff6e225e7
 SHA512:
-  metadata.gz: ed9e6c8e9cf08938177b687496f83e58e7ecbf0a35cda2f9f84428f83acff381c882d33f53e2ba3bc51b0d533f577f7a93bc1c9fc2533a57d79bd479a80a550f
-  data.tar.gz: 36cc532f949768e70bf1582a9c652db79e5900811ebe0a4e08bd9a4840442b346c6c93cedd0d6d4c6d2d39bf6f487c321dd4d731c8f8533fa7d64ff65954dd85
+  metadata.gz: 15e401e45c34e2054505e2c85968cbe7b81b20b7e987b2034acce71ece1d8fb48ebf5906a2166c957cd6bbdb3f3a8e7fccdab66e27bccf1f1960288efa748f4d
+  data.tar.gz: 97a1233a8c01c6d818e5682b06164bf15d6e75f890a6aebbc0188712e0fa996d0d40b48f1d72e83f478573d0e8bc97350f7450cd254bbf5a1cb0efe1a9992ba1

data/README.md

@@ -3,12 +3,15 @@
 [![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. 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/175406011-883b2671-152c-4e6e-8716-d6c4c3ed2676.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._
 
@@ -539,6 +542,30 @@ class V1x0::UsersController
 end
 ```
 
+### Avoid migrate for request migrations
+
+Avoid using `migrate` for request migrations. If you do, one-off migrations, e.g. for webhooks
+will apply the request migrations, which 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 one-off 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
 

data/lib/request_migrations/configuration.rb

@@ -32,7 +32,7 @@ module RequestMigrations
     ##
     # versions defines past versions and their migrations.
     #
-    # @return [Hash<String, Array<String, Integer, Float>>] past versions.
+    # @return [Hash] 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.0.1"
 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

data/lib/request_migrations/migrator.rb

@@ -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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: request_migrations
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Zeke Gabrielse
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-06-23 00:00:00.000000000 Z
+date: 2022-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails