request_migrations 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9ade55e7b503c08190a46b58d68dfc35f619c9cf949c12ef98e7cb58548d2b6
-  data.tar.gz: 0e2a334989b6d79ec9296e9ef3c5866b42c0121e87cc2d9fa219835ff6e225e7
+  metadata.gz: 1575eecb9ad23c9dae9534b03a31acbcef8c6ed7bf46f4ffca1748ef21fcead4
+  data.tar.gz: 141dbbf4576e8b2da641ab32bd377173bbe61717d330c741c0b10c5cf9eff854
 SHA512:
-  metadata.gz: 15e401e45c34e2054505e2c85968cbe7b81b20b7e987b2034acce71ece1d8fb48ebf5906a2166c957cd6bbdb3f3a8e7fccdab66e27bccf1f1960288efa748f4d
-  data.tar.gz: 97a1233a8c01c6d818e5682b06164bf15d6e75f890a6aebbc0188712e0fa996d0d40b48f1d72e83f478573d0e8bc97350f7450cd254bbf5a1cb0efe1a9992ba1
+  metadata.gz: 119241518c4d8a9a954bd4918a6e2edbc0338938c7173953a406821f34f0f4da735e7819b7cc0e929be45c78a7da88f035f1456d5b98d53d6cb00b0fca1c8362
+  data.tar.gz: 5afffe316b08692daeaf2366fab161f23794b80326112a2b4c4ece1a13f0d40f8d61423aa81d4bf28c62274acf8a33dd63c01214295524cd7691c42203a71575

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,11 +3,13 @@
 [![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 gem was extracted
-from [Keygen](https://keygen.sh) and is being used in production 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/).
 
-![request_migrations diagram](https://user-images.githubusercontent.com/6979737/175406011-883b2671-152c-4e6e-8716-d6c4c3ed2676.png)
+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:
 
@@ -50,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.
 
@@ -130,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 {
@@ -189,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
 
@@ -209,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.
+
+Request migrations should [avoid using the `migrate` method](#avoid-migrate-for-request-migrations).
 
-### One-off 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
@@ -251,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
@@ -277,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
@@ -305,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 {
@@ -348,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
@@ -390,7 +407,7 @@ 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
 
@@ -544,14 +561,14 @@ 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.
+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 one-off migrations)
+  # Bad (side-effects for data migrations)
   migrate do |params|
     params[:foo] = params.delete(:bar)
   end
@@ -570,8 +587,8 @@ 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
@@ -591,7 +608,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
@@ -642,7 +659,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] past versions.
-    config_accessor(:versions) { [] }
+    # @return [Hash<String, Array<Symbol, String, Class>>] past versions.
+    config_accessor(:versions) { {} }
   end
 end

data/lib/request_migrations/gem.rb

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

data/lib/request_migrations/migration.rb

@@ -77,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
@@ -87,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
@@ -97,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)" }
 

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

metadata

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