Skip to content

Latest commit

 

History

History
195 lines (132 loc) · 4.19 KB

README.ja.md

File metadata and controls

195 lines (132 loc) · 4.19 KB
Raw

Trabox

[Japanese][English]

Transactional-Outbox for Rails.

機能

  • Transactional-Outbox パターンでのイベントデータ公開
  • 複数のデータベース・Outbox テーブルに対応
  • publish/subscribeメソッドをもつ自作の publisher/subscriber を使用可能
  • dogstatsd ベースのメトリクス
  • 受信するメッセージの順序を維持する

サポートしている publisher

  • Google Cloud Pub/Sub

必要条件

  • Ruby 2.6+
  • Rails 6.0+

インストール

Gemfileに下記を追記

gem 'trabox'

下記コマンドを実行

bundle install
bin/rails g trabox:configure

これで、config/initializers/trabox.rbファイルが生成されます。

オプション

bundle binstubs trabox

使い方

outbox テーブルの作成

下記コマンドで outbox モデルのファイルが作成されます。
bin/rails g modelのオプションを使えるので、必要に応じて変更してください。

# generate model
bin/rails g trabox:model <NAME>

# Help
$ bin/rails g trabox:model --help
Usage:
  rails generate trabox:model NAME [field[:type][:index] field[:type][:index]] [options]
...

追加のオプション: --polymorphic=<NAME> オプションをつけるとreferencesカラムが追加されます。
このオプションはイミュータブルデータモデルに基づいた設計のときにイベントデータと outbox データを関連づけるのに使用します。

例：bin/rails g trabox:model event --polymorphic=event

class CreateEvents < ActiveRecord::Migration[6.1]
  def change
    create_table :events do |t|
      t.references :event, polymorphic: true, null: false # --polymorphicオプションで生成されたカラム
      t.binary :event_data
      t.string :message_id
      t.datetime :published_at

      t.timestamps
    end
  end
end

Event データの登録

Publish するイベントデータを作成した outbox テーブルに登録します。

# Your rails application
ActiveRecord::Base.transaction do
  user = User.create! name: 'hoge'

  Event.create! event_data: <serialized_user_event>
end

Relayer 実行

bin/trabox relay

# Help
bin/trabox relay -h
Usage: trabox relay [OPTIONS]

Overwrite configuration

    -l, --limit NUM
    -i, --interval SEC
    -L, --[no-]lock
        --log-level LEVEL

Subscriber 実行

bin/trabox subscribe

# Help
 bin/trabox subscribe -h
Usage: trabox subscribe [OPTIONS]

Overwrite configuration

        --log-level LEVEL

メトリクス

メトリクスの名前空間の初期値はtraboxです。
名前空間はTRABOX_METRIC_NAMESPACE環境変数で変更可能です。

名前 説明
unpublished_event_count パブリッシュするイベント数
published_event_count パブリッシュしたイベント数
find_events_error_count パブリッシュするイベントの取得に失敗した数
publish_event_error_count イベントのパブリッシュに失敗した数
update_event_record_error_count パブリッシュしたイベントのカラム更新に失敗した数

Health check

command metric name
relay relay.service.check
subscribe subscribe.service.check

Sequence diagram

Contributing

Bug reports and pull requests are welcome.

Development

Install gems

bundle install

Start mysql / pubsub emulator

docker-compose up

setup db

cd spec/rails_app
bin/rails db:setup

create topic / subscribe

rake trabox:pubsub_setup

Test

bin/rspec

License

The gem is available as open source under the terms of the MIT License.