OpenAPI v3.0.0のCallback Objectについて調べた

2017年7月末リリースのOpenAPI v3.0.0に入ったCallback Objectという仕様がパッと見だとどう使うかわかりにくかったので、調べてみました。

Callback Objectの仕様は次のリンク先のとおりです。

OpenAPI-Specification/3.0.0.md at master · OAI/OpenAPI-Specification

Callack Objectについて簡単に述べると、「OpenAPIドキュメントで記述しているエンドポイントに対してリクエストしたあと、こちらが指定したエンドポイントに対してリクエスト先がwebhookなどでコールバックするような場合についての仕様が記述できるもの」、です。

まだわかりにくいので、OpenAPI公式のリポジトリに置いてある次のサンプルを見てみます。

まず、このYAML中のキー post 配下を見てみると次のようになっています(抜粋)。

post:
  description: subscribes a client to receive out-of-band data
  parameters:
    - name: callbackUrl
      in: query
      required: true
      description: # ...
      schema:
        type: string
        format: uri
        example: https://tonys-server.com
  responses:
    '201':
      description: subscription successfully created
      content:
        application/json:
          schema:
            description: subscription information
            required:
              - subscriptionId
            properties:
              subscriptionId:
                description: this unique identifier allows management of the subscription
                type: string
                example: 2531329f-fb09-4ef7-887e-84e648214436

ここでは、

  • /streams というエンドポイントに対して callbackUrl というパラメータとともにPOSTリクエストを投げることができる
  • リクエストが成功すると subscription(購読)リソースが作成される

というエンドポイント仕様が記述されていることがわかります。

parameters, responses のさらに下の callbacks 配下にある記述が、今回着目するCallbacks Objectです(抜粋)。

callbacks:
  onData:
    '{$request.query.callbackUrl}/data':
      post:
        requestBody:
          description: subscription payload
          content:
            application/json:
              schema:
                properties:
                  timestamp:
                    type: string
                    format: date-time
                  userData:
                    type: string
        responses:
          '202':
            description: # ...
          '204':
            description: # ...

これは、このAPIを提供している側(仕様書内ではAPI providerと呼ばれています)はクライアント側が指定した '{$request.query.callbackUrl}/data' というURLに対して requestBody の内容でPOSTリクエストするようになるという記述です。

ここで、$request.query.callbackUrl のようなデータの指定方法は仕様書の Key Expression の項に書いてあるURL, HtTPメソッド、HTTPリクエストのデータ、HTTPレスポンスの Location ヘッダが取得できる「実行時式」(runtime expression) です。

responses には返すべきステータスコードなどが記述できます。ここでいうエンドポイント '{$request.query.callbackUrl}/data' を持つホストは responses に書いた記述を満たすようにレスポンスを返す必要があります。

以上のようにして、Callback Objectを使うことで、あるエンドポイントに付随したAPI provider側からのコールバックについての仕様も記述できるようになります。

Rails 5.1でRails pluginをセットアップする手順

最近読んでいる “Crafting Rails 4 Applications” の中でRails pluginを開発する場面が多々あるので、手元でもRails 5を使ってRails pluginを書いてみています。

Rails 5だと、プラグインのセットアップ手順が本の記述やRails Guidesの記述と少し違っていたので書いておきます。

環境は次のとおりです。

  • Ruby 2.4.1
  • Rails 5.1.3
  • Bundler 1.14.6

プラグインの新規作成

$ rails plugin new my_plugin
      create
      create  README.md
      create  Rakefile
      create  my_plugin.gemspec
      create  MIT-LICENSE
      create  .gitignore
      create  Gemfile
      create  lib/my_plugin.rb
      create  lib/tasks/my_plugin_tasks.rake
      create  lib/my_plugin/version.rb
      create  bin/test
      create  test/test_helper.rb
      create  test/my_plugin_test.rb
      append  Rakefile
  vendor_app  test/dummy

gemのインストール

$ cd my_plugin
$ bundle
You have one or more invalid gemspecs that need to be fixed.
The gemspec at /Users/kymmt/my_plugin/my_plugin.gemspec is not valid. Please fix this gemspec.
The validation error was '"FIXME" or "TODO" is not a description'

Rails pluginはgemの一種なのでプロジェクト中に *.gemspec ファイルを持ちます。plugin作成時はこの gemspec 中の次の項目に TODO の文字列が入っていて、これだと gemspec がinvalidと判定され先に進めないので、消すなりなんなりします。

Gem::Specification.new do |s|
  # ...
  s.homepage    = "TODO" # TODOを消す
  s.summary     = "TODO: Summary of MyPlugin." # TODOを消す
  s.description = "TODO: Description of MyPlugin." # TODOを消す
  # ...
end

もう1回 bundle するとgemが入ります。

$ bundle
Fetching gem metadata from https://rubygems.org/..........
(snip)
Bundle complete! 2 Gemfile dependencies, 40 gems now installed.
Gems in the groups production and rmagick were not installed.
Use `bundle show [gemname]` to see where a bundled gem is installed.

テストの実行

“Crafting Rails 4 Applications” には「rake test でテストを実行できる」という旨の記述がありますが、これをやると次のようになります。

$ rake test
/Users/kymmt/my_plugin/test/dummy/db/schema.rb doesn't exist yet. Run `rails db:migrate` to create it, then try again. If you do not intend to use a database, you should instead alter /Users/kymmt/my_plugin/test/dummy/config/application.rb to limit the frameworks that will be loaded.
/Users/kymmt/my_plugin/test/test_helper.rb:9:in `<top (required)>': uninitialized constant Rails::TestUnitReporter (NameError)
        from /Users/kymmt/my_plugin/test/my_plugin_test.rb:1:in `require'
        from /Users/kymmt/my_plugin/test/my_plugin_test.rb:1:in `<top (required)>'
        from /Users/kymmt/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/rake-12.0.0/lib/rake/rake_test_loader.rb:15:in `require'
        from /Users/kymmt/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/rake-12.0.0/lib/rake/rake_test_loader.rb:15:in `block in <main>'
        from /Users/kymmt/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/rake-12.0.0/lib/rake/rake_test_loader.rb:4:in `select'
        from /Users/kymmt/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/rake-12.0.0/lib/rake/rake_test_loader.rb:4:in `<main>'
rake aborted!
Command failed with status (1)

Tasks: TOP => test
(See full trace by running task with --trace)

テスト用ダミーアプリケーションのDBマイグレーションができていないので、ダミーアプリケーションのルートディレクトリまで降りてから、DBマイグレーションを実行します。

$ cd test/dummy
$ rake db:migrate
$ cat db/schema.rb
# This file is auto-generated from the current state of the database. Instead
# of editing this file, please use the migrations feature of Active Record to
# incrementally modify your database, and then regenerate this schema definition.
#
# Note that this schema.rb definition is the authoritative source for your
# database schema. If you need to create the application database on another
# system, you should be using db:schema:load, not running all the migrations
# from scratch. The latter is a flawed and unsustainable approach (the more migrations
# you'll amass, the slower it'll run and the greater likelihood for issues).
#
# It's strongly recommended that you check this file into your version control system.

ActiveRecord::Schema.define(version: 0) do

end

これで、もう1回テストを実行すると、今度は次のエラーになります。

$ cd ../../
$ rake test
/Users/kymmt/my_plugin/test/test_helper.rb:9:in `<top (required)>': uninitialized constant Rails::TestUnitReporter (NameError)
        from /Users/kymmt/my_plugin/test/my_plugin_test.rb:1:in `require'
        from /Users/kymmt/my_plugin/test/my_plugin_test.rb:1:in `<top (required)>'
        from /Users/kymmt/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/rake-12.0.0/lib/rake/rake_test_loader.rb:15:in `require'
        from /Users/kymmt/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/rake-12.0.0/lib/rake/rake_test_loader.rb:15:in `block in <main>'
        from /Users/kymmt/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/rake-12.0.0/lib/rake/rake_test_loader.rb:4:in `select'
        from /Users/kymmt/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/rake-12.0.0/lib/rake/rake_test_loader.rb:4:in `<main>'
rake aborted!
Command failed with status (1)

Tasks: TOP => test
(See full trace by running task with --trace)

これは test/test_helper.rbRails::TestUnitReporter を読み込んでないのが原因で、test/test_helper.rbrequire 'rails/test_unit/reporter' を加えれば動くようになります*1

ですが、実は “The Basics of Creating Rails Plugins — Ruby on Rails Guides” の第2節に書いてあるとおり、テストを実行するには bin/test を実行するだけでOKです。これは bin/test の中で rails/plugin/testrequire しており、その rails/plugin/test では Rails::TestUnitReporterrequire_relative されているからです*2

$ bin/test
Run options: --seed 60803

# Running:

.

Finished in 0.002613s, 382.6843 runs/s, 382.6843 assertions/s.
1 runs, 1 assertions, 0 failures, 0 errors, 0 skips

参考

Crafting Rails 4 Applications: Expert Practices for Everyday Rails Development (The Facets of Ruby)

Crafting Rails 4 Applications: Expert Practices for Everyday Rails Development (The Facets of Ruby)

GraphQL::Batchのサンプルコードを読む & 使ってみる

単純にGraphQLクエリを投げると、サーバサイドでの関連を含むレコード取得時にN+1問題が発生することがあります。こういうケースでは、複数のデータ取得リクエストをひとまとめにして、単一のリクエストとしてDBからデータを取得するbatchingが推奨されています*1

GraphQLにおけるbatchingをgraphql gemを使ってやるためのGraphQL::Batchというgemがあります。先日リポジトリにサンプルコードが追加されて使いかたを把握しやすくなったので、サンプルコードを読みながら使ってみます。

github.com

GraphQL::Batchの概要

GraphQL::Batchでは、Loaderというデータを取得するためのクラスを作って使うことが想定されています。これは、Facebookが開発しているDataLoaderでの考えかたが元となっています。Loaderがbatchingでデータを取得するときは、load 関数でレコードのキーを複数受け取り、複数レコードを解決するpromiseを返します*2

利用例

コードを読む前にGraphQL::Batchの利用例を示します。

前提

本エントリではRailsでGraphQL::Batchを使うこととします*3

次のようなモデルが存在するRailsアプリケーションを考えます。DBテーブルもこれにしたがった構成であるとします。

class User < ApplicationRecord
  has_many :customers
end

class Customer < ApplicationRecord
  belongs_to :user
  has_many :orders
  has_many :deliverers, through: :orders
end

class Deliverer < ApplicationRecord
  has_many :orders
  has_many :customers, through: :orders
end

class Order < ApplicationRecord
  belongs_to :customer
  belongs_to :deliverer
end

このとき、次のようなGraphQLのスキーマを app/graphql/types 配下などに定義するとします。

Types::QueryType = GraphQL::ObjectType.define do
  name 'Query'

  field :user do
    type Types::UserType
    argument :email, !types.String
    resolve ->(obj, args, ctx) {
      User.find_by!(email: args['email'])
    }
  end
end

Types::UserType = GraphQL::ObjectType.define do
  name 'User'

  field :email, !types.String
  connection :customers, Types::CustomerType.connection_type
end

Types::CustomerType = GraphQL::ObjectType.define do
  name 'Customer'

  field :name, !types.String
  connection :orders, Types::OrderType.connection_type
  connection :deliverers, Types::DelivererType.connection_type
end

Types::DelivererType = GraphQL::ObjectType.define do
  name 'Deliverer'

  field :name, !types.String
  connection :orders, Types::OrderType.connection_type
  connection :customers, Types::CustomerType.connection_type
end

Types::OrderType = GraphQL::ObjectType.define do
  name 'Order'

  field :price, !types.Int
  field :customer, !Types::CustomerType
  field :deliverer, !Types::DelivererType
end

ここで、次のようなクエリをサーバへ投げてみます(DBにはいい感じにデータが保存されているとします)。

{
  user(email: "foo@example.com") {
    customers(first: 2) {
      edges {
        node {
          orders {
            edges {
              node {
                deliverer {
                  name
                }
              }
            }
          }
        }
      }
    }
  }
}

すると、次のように Customer のレコードごとに Order を、Order のレコードごとに Deliverer を取得するSQLを発行してしまうN+1問題が発生します。

User Load (1.6ms)  SELECT  "users".* FROM "users" WHERE "users"."email" = ? LIMIT ?  [["email", "foo@example.com"], ["LIMIT", 1]]
Customer Load (1.7ms)  SELECT  "customers".* FROM "customers" WHERE "customers"."user_id" = ? LIMIT ?  [["user_id", 1], ["LIMIT", 2]]
Order Load (3.3ms)  SELECT "orders".* FROM "orders" WHERE "orders"."customer_id" = ?  [["customer_id", 1]]
Deliverer Load (1.8ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 1], ["LIMIT", 1]]
Deliverer Load (1.5ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 2], ["LIMIT", 1]]
Deliverer Load (1.4ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 1], ["LIMIT", 1]]
Deliverer Load (2.1ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 2], ["LIMIT", 1]]
Deliverer Load (2.6ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 1], ["LIMIT", 1]]
Deliverer Load (2.9ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 2], ["LIMIT", 1]]
Deliverer Load (1.8ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 1], ["LIMIT", 1]]
Deliverer Load (1.9ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 2], ["LIMIT", 1]]
Deliverer Load (1.6ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 1], ["LIMIT", 1]]
Deliverer Load (1.8ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 2], ["LIMIT", 1]]
Order Load (2.1ms)  SELECT "orders".* FROM "orders" WHERE "orders"."customer_id" = ?  [["customer_id", 2]]
Deliverer Load (1.5ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 1], ["LIMIT", 1]]
Deliverer Load (1.4ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 2], ["LIMIT", 1]]
Deliverer Load (1.5ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 1], ["LIMIT", 1]]
Deliverer Load (1.6ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 2], ["LIMIT", 1]]
Deliverer Load (2.2ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 1], ["LIMIT", 1]]
Deliverer Load (1.7ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 2], ["LIMIT", 1]]
Deliverer Load (1.6ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 1], ["LIMIT", 1]]
Deliverer Load (1.4ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 2], ["LIMIT", 1]]
Deliverer Load (1.5ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 1], ["LIMIT", 1]]
Deliverer Load (2.6ms)  SELECT  "deliverers".* FROM "deliverers" WHERE "deliverers"."id" = ? LIMIT ?  [["id", 2], ["LIMIT", 1]]

GraphQL::Batchの利用

上述したN+1問題を解消するためにGraphQL::Batchを使います。具体的には次のことをやります。

  • サンプルを参考にLoaderを定義する
  • スキーマ定義の resolve 内で使う

まず、サンプルを参考にして、Loaderを app/graphql/loaders 配下などに定義しておきます。そして、定義したLoaderを使って次のようにスキーマを定義し直します。変更部分だけ抜粋します。

Types::UserType = GraphQL::ObjectType.define do
  # ...
  connection :customers, Types::CustomerType.connection_type do
    resolve ->(user, args, ctx) {
      Loaders::AssociationLoader.for(User, :customers).load(user)
    }
  end
end

Types::CustomerType = GraphQL::ObjectType.define do
  # ...
  connection :orders, Types::OrderType.connection_type do
    resolve ->(customer, args, ctx) {
      Loaders::AssociationLoader.for(Customer, :orders).load(customer)
    }
  end
  connection :deliverers, Types::DelivererType.connection_type do
    resolve ->(customer, args, ctx) {
      Loaders::AssociationLoader.for(Customer, :deliverers).load(customer)
    }
  end
end

Types::DelivererType = GraphQL::ObjectType.define do
  # ...
  connection :orders, Types::OrderType.connection_type do
    resolve ->(deliverer, args, ctx) {
      Loaders::AssociationLoader.for(Deliverer, :orders).load(deliverer)
    }
  end
  connection :customers, Types::CustomerType.connection_type do
    resolve ->(deliverer, args, ctx) {
      Loaders::AssociationLoader.for(Deliverer, :customers).load(deliverer)
    }
  end
end

Types::OrderType = GraphQL::ObjectType.define do
  # ...
  field :customer, !Types::CustomerType do
    resolve ->(order, args, ctx) {
      Loaders::RecordLoader.for(Customer).load(order.customer_id)
    }
  end
  field :deliverer, !Types::DelivererType  do
    resolve ->(order, args, ctx) {
      Loaders::RecordLoader.for(Deliverer).load(order.deliverer_id)
    }
  end
end

この状態で先ほどと同じクエリを送信すると、Order, Deliverer に対するSQLがまとめて発行されるようになり、N+1問題を防いでいることがログを見るとわかります。

User Load (1.6ms)  SELECT  "users".* FROM "users" WHERE "users"."email" = ? LIMIT ?  [["email", "foo@example.com"], ["LIMIT", 1]]
Customer Load (1.5ms)  SELECT "customers".* FROM "customers" WHERE "customers"."user_id" = 1
Order Load (2.2ms)  SELECT "orders".* FROM "orders" WHERE "orders"."customer_id" IN (1, 2, 3, 4)
Deliverer Load (1.5ms)  SELECT "deliverers".* FROM "deliverers" WHERE "deliverers"."id" IN (1, 2)

それでは、このLoaderが何をやっているかを見ていきます。

Loaderサンプルコードリーディング

次の場所にある RecordLoaderAssociationLoader のコードを読んで何をやっているか見ていきます。

なお、Loaderを作るには GraphQL::Batch::Loader を継承する必要があります。

RecordLoader

コードはこちら。

belongs_to のように関連先が1件のときに使うLoaderです。上述した例では Order で利用しています。

Graphql::Batch::Loader はファクトリメソッド for から initialize を使っており、この initialize を必要に応じてオーバーライドしていきます。ここでは model で関連先モデルのクラス名を渡せるようになっています。column はデフォルトでは主キー(Active Recordのデフォルトではサロゲートキー id)ですが、オプションで別のキーも渡せるようになっています。また、特定レコードだけ絞り込むために where を渡せるようになっています。

def initialize(model, column: model.primary_key, where: nil)
  @model = model
  @column = column.to_s
  @column_type = model.type_for_attribute(@column)
  @where = where
end

load へはバッチで取得してほしいレコードのキーを渡します。ここでは @column_type の表す型にキャストしてから親クラス GraphQL::Batch::Loaderload に引数を渡しています。これは、任意の主キーを適切な型に変換する処理と思われます。

def load(key)
  super(@column_type.cast(key))
end

perform へは、バッチで渡ってくる keys をもとに、一気にレコードをロード、つまりbatchingする処理を書きます。このときに、プライベートメソッド query で、initialize で渡された絞り込み条件と perform の引数 keys をもとに、必要な関連先レコードだけロードしています。その後、fulfill することで、promiseを解決状態に遷移させつつ、ロードしたレコードを渡しています。GraphQL::Batch::Loader#fulfill の定義は次を参照してください。

また、対応するレコードが存在しない keys 中のキーのpromiseも解決状態とするために、最後の行で fulfill できていない keys の要素に対して、レコードが存在しなかったという意味合いで nil を渡して fulfill しています。

def perform(keys)
  query(keys).each do |record|
    value = @column_type.cast(record.public_send(@column))
    fulfill(value, record)
  end
  keys.each { |key| fulfill(key, nil) unless fulfilled?(key) }
end

private

def query(keys)
  scope = @model
  scope = scope.where(@where) if @where
  scope.where(@column => keys)
end

AssociationLoader

コードはこちら。

has_many のように関連先が複数件あるときに使うLoaderです。上述した例では User, Customer, Deliverer で利用しています。

initialize では関連元モデルのクラス名 model と、モデル内で has_many に指定する関連先名 association_name を渡しています。最後の行の validate では、model が本当に association_name で指定される関連を持っているのかをチェックしています。

def initialize(model, association_name)
  @model = model
  @association_name = association_name
  validate
end

private

def validate
  unless @model.reflect_on_association(@association_name)
    raise ArgumentError, "No association #{@association_name} on #{@model}"
  end
end

perform では、バッチで渡ってくる関連元レコード群に対する関連先を preload_association 内の ActiveRecord::Associations::Preloader#preload で一気にpreloadしています。このメソッドは :nodoc: なRailsの内部APIですが、ここでは利便性をとって使われているようです。その後、RecordLoader と同じように、ロードした各レコードに対して fulfill することで、promiseを解決状態にしつつ、eager loadしたレコードを渡しています。

def perform(records)
  preload_association(records)
  records.each { |record| fulfill(record, read_association(record)) }
end

private

def preload_association(records)
  ::ActiveRecord::Associations::Preloader.new.preload(records, @association_name)
end

def read_association(record)
  record.public_send(@association_name)
end

順番が前後しますが、load へはバッチで関連先を取得してほしい関連元レコードを渡します。ここで、すでに関連先レコードを perform でロード済みであれば、batchingの対象とすることなく、そのレコードを持つ解決済みpromiseをすぐに返しています。

def load(record)
  raise TypeError, "#{@model} loader can't load association for #{record.class}" unless record.is_a?(@model)
  return Promise.resolve(read_association(record)) if association_loaded?(record)
  super
end

private

def association_loaded?(record)
  record.association(@association_name).loaded?
end

おわりに

サンプルコードを試しつつ読みながらGraphQL::Batchをどう使うか調べました。具体的には次のようにすればひとまず使えそうです。

  • サンプルを参考にLoaderを定義する
  • スキーマ定義の resolve 内で使う

私が試しに書き散らしたコードは次の場所に置いています。

github.com

*1:GraphQL Best Practices | GraphQL

*2:https://github.com/facebook/dataloader#batching

*3:GraphQL::BatchはActive Recordに依存しているわけではありません