request_migrations 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a07f06f1ea7b2b51851ff1490e1233363bc4d13bc6ac8918e7c1d886c9497ffd
-  data.tar.gz: 79f9bb8c317e906b4d4d6992811156103265d902f82ca0fcc1ac65a6e85327de
+  metadata.gz: 03674ecf6a2120accd4fcbbbe4add7f73a94098e08882a65630085b3dcc38ecd
+  data.tar.gz: 38b32703419f8857737fc0b8fa61d5ada954f69c201247892441291b901ed0fb
 SHA512:
-  metadata.gz: 595d53c2b5d25dd34d4212e9db9208b96dccf684ec03e4cd75fa485d5421c400cc0b465e4914d7613a3ef15c08757b93ce163cebf1cb886dccf14e7986ca16bb
-  data.tar.gz: 95cd329eee002333f976886c2394a538dc1f3e6231f093a4d7155b9330eaf0725dc9ed38e31c6ccc0d9e7fdeb6a32b7f54970dc6114064b6286b96888b0be4d2
+  metadata.gz: ed9e6c8e9cf08938177b687496f83e58e7ecbf0a35cda2f9f84428f83acff381c882d33f53e2ba3bc51b0d533f577f7a93bc1c9fc2533a57d79bd479a80a550f
+  data.tar.gz: 36cc532f949768e70bf1582a9c652db79e5900811ebe0a4e08bd9a4840442b346c6c93cedd0d6d4c6d2d39bf6f487c321dd4d731c8f8533fa7d64ff65954dd85

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.0.0
+
+- Initial release.
+
 ## 0.1.0
 
 - Test release.

data/README.md

@@ -49,6 +49,7 @@ _We're working on improving the docs._
 - Define migrations for migrating a request between versions.
 - Define migrations for applying one-off migrations.
 - Define version-based routing constraints.
+- It's fast.
 
 ## Usage
 
@@ -138,7 +139,7 @@ RequestMigrations.configure do |config|
 
   # Define previous versions and their migrations, in descending order.
   config.versions = {
-    '1.0' => %i[combine_user_names_migration],
+    '1.0' => %i[combine_names_for_user_migration],
   }
 end
 ```
@@ -149,6 +150,14 @@ are applied:
 ```ruby
 class ApplicationController < ActionController::API
   include RequestMigrations::Controller::Migrations
+
+  # Optionally rescue from requests for unsupported versions
+  rescue_from RequestMigrations::UnsupportedVersionError, with: -> {
+    render(
+      json: { error: 'unsupported API version requested', code: 'INVALID_API_VERSION' },
+      status: :bad_request,
+    )
+  }
 end
 ```
 
@@ -269,6 +278,8 @@ 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.
 
+In addition to one-off migrations, this allows for easier testing.
+
 ### Routing constraints
 
 When you want to encourage API clients to upgrade, you can utilize a routing `version_constraint`
@@ -324,9 +335,8 @@ RequestMigrations.configure do |config|
     ],
   }
 
-  # Use a custom logger. Must be a tagged logger. Defaults to
-  # using Rails.logger.
-  config.logger = ActiveSupport::TaggedLogging.new(...)
+  # Use a custom logger. Supports ActiveSupport::TaggedLogging.
+  config.logger = Rails.logger
 end
 ```
 
@@ -343,11 +353,43 @@ to instead use one of the following, set via `config.version_format=`.
 | `: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
+## Testing
+
+Using one-offs allows for easier testing of migrations. For example, using Rspec:
+
+```ruby
+describe CombineNamesForUserMigration do
+  before do
+    RequestMigrations.configure do |config|
+      config.current_version = '1.1'
+      config.versions        = {
+        '1.0' => [CombineNamesForUserMigration],
+      }
+    end
+  end
+
+  it 'should migrate user name attributes' do
+    migrator = RequestMigrations::Migrator.new(from: '1.1', to: '1.0')
+    data     = serialize(
+      create(:user, first_name: 'John', last_name: 'Doe'),
+    )
+
+    expect(data).to include(type: 'user', first_name: 'John', last_name: 'Doe')
+    expect(data).to_not include(name: anything)
+
+    migrator.migrate!(data:)
+
+    expect(data).to include(type: 'user', name: 'John Doe')
+    expect(data).to_not include(first_name: 'John', last_name: 'Doe')
+  end
+end
+```
+
+## 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
+### Use pattern matching
 
 Pattern matching really cleans up the `:if` conditions, and overall makes migrations more readable.
 
@@ -382,7 +424,7 @@ end
 
 Just be sure to remember your `else` block when `case` pattern matching. :)
 
-#### Route helpers
+### Route helpers
 
 If you need to use route helpers in a migration, include them in your migration:
 
@@ -392,7 +434,7 @@ class SomeMigration < RequestMigrations::Migration
 end
 ```
 
-#### Separate by shape
+### 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
@@ -454,7 +496,7 @@ end
 
 Note that the `migrate` method now migrates an array input, and matches on the `#index` route.
 
-#### Always check response status
+### Always check response status
 
 Always check a response's status. You don't want to unintentionally apply migrations to error
 responses.
@@ -467,7 +509,9 @@ class SomeMigration < RequestMigrations::Migration
 end
 ```
 
-#### Don't match on URL pattern
+Also mind `204 No Content`, since the response body will be `nil`.
+
+### 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.
@@ -482,7 +526,7 @@ class SomeMigration < RequestMigrations::Migration
 end
 ```
 
-#### Namespace deprecated controllers
+### 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.
@@ -496,7 +540,7 @@ end
 ```
 
 
-#### Avoid routing contraints
+### 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
@@ -518,6 +562,61 @@ Rails.application.routes.draw do
 end
 ```
 
+### Avoid n+1s
+
+Avoid introducing n+1 queries in your migration. Try to utilize the current data you have
+to perform more meaningful queries, returning only the data needed for the migration.
+
+```ruby
+class AddRecentPostToUsersMigration < RequestMigrations::Migration
+  description %(adds :recent_post association to a collection of users)
+
+  # Bad (n+1)
+  migrate if: -> data { data in [*, { type: 'user' }, *] do |data|
+    data.each do |record|
+      case record
+      in type: 'user', id:
+        recent_post = Post.reorder(created_at: :desc)
+                          .find_by(user_id: id)
+
+        record[:recent_post] = recent_post&.id
+      else
+      end
+    end
+  end
+
+  # Good
+  migrate if: -> data { data in [*, { type: 'user' }, *] do |data|
+    user_ids = data.collect { _1[:id] }
+    post_ids = Post.select(:id, :user_id)
+                   .distinct_on(:user_id)
+                   .where(user_id: user_ids)
+                   .reorder(created_at: :desc)
+                   .group_by(&:user_id)
+
+    data.each do |record|
+      case record
+      in type: 'user', id: user_id
+        record[:recent_post] = post_ids[user_id]&.id
+      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
+```
+
+Instead of potentially tens or hundreds of queries, we make a single purposeful query
+to get the data we need to complete the migration.
+
 ---
 
 Have a tip of your own? Open a pull request!

data/lib/request_migrations/configuration.rb

@@ -4,10 +4,35 @@ module RequestMigrations
   class Configuration
     include ActiveSupport::Configurable
 
-    config_accessor(:logger)                   { Rails.logger }
+    ##
+    # logger defines the logger used by request_migrations.
+    #
+    # @return [Logger] the logger.
+    config_accessor(:logger) { Logger.new("/dev/null") }
+
+    ##
+    # request_version_resolver defines how request_migrations should resolve the
+    # current version of a request.
+    #
+    # @return [Proc] the request version resolver.
     config_accessor(:request_version_resolver) { -> req { self.current_version } }
-    config_accessor(:version_format)           { :semver }
-    config_accessor(:current_version)          { nil }
-    config_accessor(:versions)                 { [] }
+
+    ##
+    # version_format defines the version format.
+    #
+    # @return [Symbol] format
+    config_accessor(:version_format) { :semver }
+
+    ##
+    # current_version defines the latest version.
+    #
+    # @return [String, Integer, Float] 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) { [] }
   end
 end

data/lib/request_migrations/controller.rb

@@ -2,6 +2,8 @@
 
 module RequestMigrations
   module Controller
+    ##
+    # @private
     class Migrator < Migrator
       def initialize(request:, response:, **kwargs)
         super(**kwargs)
@@ -35,9 +37,24 @@ module RequestMigrations
       attr_accessor :request,
                     :response
 
-      def logger = RequestMigrations.logger.tagged(request&.request_id)
+      def logger
+        if RequestMigrations.config.logger.respond_to?(:tagged)
+          RequestMigrations.logger.tagged(request&.request_id)
+        else
+          RequestMigrations.logger
+        end
+      end
     end
 
+    ##
+    # Migrations is controller middleware that automatically applies migrations.
+    #
+    # @example
+    #   class ApplicationController < ActionController::API
+    #     include RequestMigrations::Controller::Migrations
+    #   end
+    #
+    # @raise [RequestMigrations::UnsupportedVersionError]
     module Migrations
       extend ActiveSupport::Concern
 
@@ -60,7 +77,7 @@ module RequestMigrations
       extend ActiveSupport::Concern
 
       included do
-        # TODO(ezekg) Implement controller-level version constraints
+        # TODO(ezekg) Implement controller-level version constraints.
       end
     end
   end

data/lib/request_migrations/gem.rb

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

data/lib/request_migrations/migration.rb

@@ -2,6 +2,8 @@
 
 module RequestMigrations
   class Migration
+    ##
+    # @private
     class ConditionalBlock
       def initialize(if: nil, &block)
         @if    = binding.local_variable_get(:if)
@@ -39,18 +41,40 @@ module RequestMigrations
         klass.response_blocks   = response_blocks.dup
       end
 
+      ##
+      # description sets the description.
+      #
+      # @param desc [String] the description
       def description(desc)
         self.description_value = desc
       end
 
+      ##
+      # request sets the request migration.
+      #
+      # @param if [Proc] the proc which determines if the migration should run.
+      #
+      # @yield [request] the block containing the migration.
       def request(if: nil, &block)
         self.request_blocks << ConditionalBlock.new(if:, &block)
       end
 
+      ##
+      # migrate sets the data migration.
+      #
+      # @param if [Proc] the proc which determines if the migration should run.
+      #
+      # @yield [data] the block containing the migration.
       def migrate(if: nil, &block)
         self.migration_blocks << ConditionalBlock.new(if:, &block)
       end
 
+      ##
+      # response sets the response migration.
+      #
+      # @param if [Proc] the proc which determines if the migration should run.
+      #
+      # @yield [response] the block containing the migration.
       def response(if: nil, &block)
         self.response_blocks << ConditionalBlock.new(if:, &block)
       end
@@ -58,18 +82,24 @@ module RequestMigrations
 
     extend DSL
 
+    ##
+    # @private
     def migrate_request!(request)
       self.class.request_blocks.each { |block|
         instance_exec(request) { block.call(self, _1) }
       }
     end
 
+    ##
+    # @private
     def migrate!(data)
       self.class.migration_blocks.each { |block|
         instance_exec(data) { block.call(self, _1) }
       }
     end
 
+    ##
+    # @private
     def migrate_response!(response)
       self.class.response_blocks.each { |block|
         instance_exec(response) { block.call(self, _1) }

data/lib/request_migrations/migrator.rb

@@ -2,11 +2,22 @@
 
 module RequestMigrations
   class Migrator
+    ##
+    # Migrator represents a versioned migration from one version to another.
+    #
+    # @param from [String, Integer, Float] the current version.
+    # @param to [String, Integer, Float] the target version.
     def initialize(from:, to:)
       @current_version = Version.new(from)
       @target_version  = Version.new(to)
     end
 
+    ##
+    # migrate! attempts to apply all matching migrations on data.
+    #
+    # @param data [*] the data to be migrated.
+    #
+    # @return [*] the migrated data.
     def migrate!(data:)
       logger.debug { "Migrating from #{current_version} to #{target_version} (#{migrations.size} potential migrations)" }
 
@@ -26,7 +37,7 @@ module RequestMigrations
 
     def logger = RequestMigrations.logger
 
-    # TODO(ezekg) These should be sorted
+    # TODO(ezekg) These should be sorted.
     def migrations
       @migrations ||=
         RequestMigrations.config.versions

data/lib/request_migrations/router.rb

@@ -3,6 +3,8 @@
 module RequestMigrations
   module Router
     module Constraints
+      ##
+      # @private
       class VersionConstraint
         def initialize(constraint:)
           @constraint = Version::Constraint.new(constraint)
@@ -19,6 +21,20 @@ module RequestMigrations
         def resolver = RequestMigrations.config.request_version_resolver
       end
 
+      ##
+      # version_constraint is a router constraint that resolves routes for
+      # specific versions.
+      #
+      # @param constraint [String] the version constraint.
+      #
+      # @yield the block when the constraint is satisfied.
+      #
+      # @example
+      #   Rails.application.routes.draw do
+      #     version_constraint '> 1.0' do
+      #       resources :some_new_resource
+      #     end
+      #   end
       def version_constraint(constraint, &)
         constraints VersionConstraint.new(constraint:) do
           instance_eval(&)

data/lib/request_migrations/version.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module RequestMigrations
+  ##
+  # @private
   class Version
     include Comparable
 

data/lib/request_migrations.rb

@@ -2,6 +2,7 @@
 
 require "active_support/concern"
 require "semverse"
+require "logger"
 require "request_migrations/gem"
 require "request_migrations/configuration"
 require "request_migrations/version"
@@ -12,20 +13,60 @@ require "request_migrations/router"
 require "request_migrations/railtie"
 
 module RequestMigrations
+  ##
+  # UnsupportedMigrationError is raised when an invalid migration is provided.
   class UnsupportedMigrationError < StandardError; end
+
+  ##
+  # InvalidVersionFormatError is raised when an badly formatted version is provided.
   class InvalidVersionFormatError < StandardError; end
+
+  ##
+  # UnsupportedVersionError is raised when an unsupported version is requested.
   class UnsupportedVersionError < StandardError; end
+
+  ##
+  # InvalidVersionError is raised when an invalid version is provided.
   class InvalidVersionError < StandardError; end
 
-  SUPPORTED_VERSION_FORMATS = %i[semver date float integer string].freeze
+  ##
+  # SUPPORTED_VERSION_FORMATS is a list of supported version formats.
+  SUPPORTED_VERSION_FORMATS = %i[
+    semver
+    date
+    float
+    integer
+    string
+  ].freeze
 
-  def self.logger = @logger ||= RequestMigrations.config.logger.tagged(:request_migrations)
+  ##
+  # config returns the current config.
   def self.config = @config ||= Configuration.new
 
+  ##
+  # logger returns the configured logger.
+  #
+  # @return [Logger]
+  def self.logger
+    @logger ||= if RequestMigrations.config.logger.respond_to?(:tagged)
+                  RequestMigrations.config.logger.tagged(:request_migrations)
+                else
+                  RequestMigrations.config.logger
+                end
+  end
+
+  ##
+  # configure yields the config.
+  #
+  # @yield [config]
   def self.configure
     yield config
   end
 
+  ##
+  # supported_versions returns an array of supported versions.
+  #
+  # @return [Array<String, Integer, Float>]
   def self.supported_versions
     [RequestMigrations.config.current_version, *RequestMigrations.config.versions.keys].uniq.freeze
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: request_migrations
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Zeke Gabrielse