request_migrations 1.0.1 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9ade55e7b503c08190a46b58d68dfc35f619c9cf949c12ef98e7cb58548d2b6
-  data.tar.gz: 0e2a334989b6d79ec9296e9ef3c5866b42c0121e87cc2d9fa219835ff6e225e7
+  metadata.gz: '091e4436fcd439967859301cc299fccaf6081f5da326ed79813e7cbce3f4d86c'
+  data.tar.gz: 4be2f76ade4958a48794ee62e6184c964f747f6c59a44a12ef20dcbbcc8c32a0
 SHA512:
-  metadata.gz: 15e401e45c34e2054505e2c85968cbe7b81b20b7e987b2034acce71ece1d8fb48ebf5906a2166c957cd6bbdb3f3a8e7fccdab66e27bccf1f1960288efa748f4d
-  data.tar.gz: 97a1233a8c01c6d818e5682b06164bf15d6e75f890a6aebbc0188712e0fa996d0d40b48f1d72e83f478573d0e8bc97350f7450cd254bbf5a1cb0efe1a9992ba1
+  metadata.gz: e2a22c88034bd0a67f34849909d85686267a4fd2a62dfbcfcb963766f678397d141a628608b63e0549581fbd9e02184a938619a269c81e44bd1a094d2febe702
+  data.tar.gz: d92878fd3a359c744c4cc9354325a5fea7d89ca81e9c3aa2718bd033a8b7ed8f7840f8bce0ada3f170dfb8f3a1ea9f1362cff8b08effafee53ffc0b5b59911c4

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:
 
@@ -15,6 +17,24 @@ Sponsored by:
 
 _A software licensing and distribution API built for developers._
 
+Links:
+
+- [Installing request_migrations](#installation)
+- [Supported Ruby versions](#supported-rubies)
+- [RubyDoc](#documentation)
+- [Usage](#usage)
+  - [Response migrations](#response-migrations)
+  - [Request migrations](#request-migrations)
+  - [Data migrations](#data-migrations)
+  - [Routing constraints](#routing-constraints)
+  - [Configuration](#configuration)
+  - [Version formats](#version-formats)
+- [Testing](#testing)
+- [Tips and tricks](#tips-and-tricks)
+- [Credits](#credits)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Installation
 
 Add this line to your application's `Gemfile`:
@@ -37,8 +57,9 @@ $ 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.
+**`request_migrations` supports Ruby 3.1 and above.** We encourage you to upgrade if you're on an older
+version. Ruby 3 provides a lot of great features, like better pattern matching and a new shorthand
+hash syntax.
 
 ## Documentation
 
@@ -50,7 +71,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.
 
@@ -122,15 +143,15 @@ 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.
+resource, and only when the response is successful. 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
+  # 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 +210,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 +235,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 +283,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 +309,20 @@ class WebhookWorker
 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.
+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 data matches
+our expected data 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](#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 +340,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 +383,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
@@ -388,9 +425,29 @@ describe CombineNamesForUserMigration do
 end
 ```
 
+To avoid polluting the global configuration, you can use `RequestMigrations::Testing`
+within your application's `spec/rails_helper.rb`, or a similar spec helper:
+
+```ruby
+require 'request_migrations/testing'
+
+Rspec.configure do |config|
+  config.before :each do
+    RequestMigrations::Testing.setup!
+  end
+
+  config.after :each do
+    RequestMigrations::Testing.teardown!
+  end
+end
+```
+
+This will setup a new test configuration, and then restore the previous global configuration
+after each spec.
+
 ## 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 +601,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 +627,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 +648,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 +699,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.1.1"
 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

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,21 @@ module RequestMigrations
   # config returns the current config.
   def self.config = @config ||= Configuration.new
 
+  ##
+  # @private
+  def self.config=(cfg)
+    raise ArgumentError, 'invalid config provided' unless
+      cfg.is_a?(Configuration)
+
+    @config = cfg
+  end
+
+  ##
+  # @private
+  def self.reset!
+    @config = 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.1
+  version: 1.1.1
 platform: ruby
 authors:
 - Zeke Gabrielse
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-06-24 00:00:00.000000000 Z
+date: 2022-07-30 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:
@@ -87,7 +88,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="