trabox 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44bcd5a8b174aa887c7cdbd415aeeba5f1af25a11e10a8a23543967ba2f4fd84
-  data.tar.gz: 0b2d81b7a826f457dd24763bf5eb39278d14061293cf75f225b54639e13057e4
+  metadata.gz: e7d6e1156090efc8e33e9618f6f449dc7363d67e58aff81324dc7300ab4d644a
+  data.tar.gz: b898fedf626581cee69767ea4f2a810e3fc242e6a6d955d6c0f284ace31d779c
 SHA512:
-  metadata.gz: 02b16217802b7beaa2c2f87e6bf60681556554c458f839c34ed7cfc049c80107be7a5646b2ae2d42de76159e4973776701cb4020987d9d2462dcad75e4183f14
-  data.tar.gz: 3b45467e241f3339de38f6502121347bc569d3b0ac9f29ff286befbbcd9d4866dd348c6a650e4fa63d901c6ba0eb3c8bfe90244bd7b812568c498366c82d4dcb
+  metadata.gz: e22b0f8227e22ac12f5605671ffbd030e9fbc1bf30b38c38194e2f8e6936b8dc6844b09078ea7e3c648e265d0b04c7f0faeb5636765a5f66515d9dbf11b29eb3
+  data.tar.gz: b47485d03057b4781b4dafd4fd9cf6668814ee58141c253f5b206a7402027cf925d0e676bc2c17e0c8d817c8878ef8516a548f724a217d231bb5abd34dbd1d48

data/README.md

@@ -1,10 +1,27 @@
 # Trabox
 
+\[[Japanese](README.ja.md)]\[[English](README.md)]
+
 Transactional-Outbox for Rails.
 
-## Usage
+![](./docs/images/architecture.jpg)
+
+## Features
+
+- Publishing event data in transactional-outbox pattern
+- Polling multiple databases and outbox tables
+- Can use your own publisher/subscriber
+- Custom Metrics with dogstatsd
+- Ensure message ordering
+
+**Supported publisher**
 
-How to use my plugin.
+- Google Cloud Pub/Sub
+
+## Requirements
+
+- Ruby 2.6+
+- Rails 6.0+
 
 ## Installation
 
@@ -17,18 +34,160 @@ gem 'trabox'
 And then execute:
 
 ```bash
-bundle
+bundle install
+bin/rails g trabox:configure
+```
+
+This will generate config file `config/initializers/trabox.rb`.
+
+**Optional**:
+
+```bash
+bundle binstubs trabox
+```
+
+## Usage
+
+### Generate outbox tables
+
+```bash
+# 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]
+...
+```
+
+**additional option: --polymorphic=\<NAME>**
+This option is inserted references column in generated outbox model.
+This use to associate event record with outbox record when the application is designed immutable data model.
+
+example:`bin/rails g trabox:model event --polymorphic=event`
+
+```ruby
+class CreateEvents < ActiveRecord::Migration[6.1]
+  def change
+    create_table :events do |t|
+      t.references :event, polymorphic: true, null: false # additional column
+      t.binary :event_data
+      t.string :message_id
+      t.datetime :published_at
+
+      t.timestamps
+    end
+  end
+end
+```
+
+### Registering event data
+
+Insert events to publish into the generated outbox table as part of the local transaction.
+
+```ruby
+# Your rails application
+ActiveRecord::Base.transaction do
+  user = User.create! name: 'hoge'
+
+  Event.create! event_data: <serialized_user_event>
+end
 ```
 
-Or install it yourself as:
+### Running relayer
 
 ```bash
-gem install trabox
+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
+
+
 ```
 
+### Running subscriber
+
+```bash
+bin/trabox subscribe
+
+# Help
+bin/trabox subscribe -h
+Usage: trabox subscribe [OPTIONS]
+
+Overwrite configuration
+
+        --log-level LEVEL
+```
+
+## Metrics
+
+The default namespace of metrics is `trabox`.  
+The namespace can be changed with `TRABOX_METRIC_NAMESPACE` environment variable.
+
+| name                            | description                                  |
+| ------------------------------- | -------------------------------------------- |
+| unpublished_event_count         | Number of events that will be published      |
+| published_event_count           | Number of published events                   |
+| find_events_error_count         | Number of errors that find events to publish |
+| publish_event_error_count       | Number of publication errors                 |
+| update_event_record_error_count | Number of record update errors               |
+
+### Health check
+
+| command   | metric name             |
+| --------- | ----------------------- |
+| relay     | relay.service.check     |
+| subscribe | subscribe.service.check |
+
+## Sequence diagram
+
+![](./docs/images/sequence-diagram.svg)
+
 ## Contributing
 
-Contribution directions go here.
+Bug reports and pull requests are welcome.
+
+## Development
+
+### Install gems
+
+```bash
+bundle install
+```
+
+### Start mysql / pubsub emulator
+
+```bash
+docker-compose up
+```
+
+**setup db**
+
+```bash
+cd spec/rails_app
+bin/rails db:setup
+```
+
+**create topic / subscribe**
+
+```bash
+rake trabox:pubsub_setup
+```
+
+### Test
+
+```bash
+bin/rspec
+```
 
 ## License
 

data/Rakefile

@@ -1,3 +1,49 @@
-require "bundler/setup"
+require 'bundler/setup'
 
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+
+namespace :trabox do
+  desc 'create topic/subscribe'
+  task :pubsub_setup do
+    require 'google/cloud/pubsub'
+    require 'logger'
+
+    ENV['PUBSUB_EMULATOR_HOST'] ||= 'localhost:8085'
+    ENV['GOOGLE_CLOUD_PROJECT'] ||= 'trabox'
+
+    logger = Logger.new($stdout)
+
+    topic_id = ENV['PUBSUB_TOPIC_ID'] || 'trabox'
+    subscription_id = ENV['PUBSUB_SUBSCRIPTION_ID'] || 'trabox-sub'
+
+    pubsub = Google::Cloud::Pubsub.new
+
+    ##################
+    #  create topic  #
+    ##################
+
+    logger.info 'Create Topic'
+
+    topic = pubsub.topic topic_id
+
+    topic&.delete
+
+    topic = pubsub.create_topic topic_id
+
+    puts "Topic #{topic.name} created."
+
+    #########################
+    #  create subscription  #
+    #########################
+
+    logger.info 'Create Subscription'
+
+    subscription = topic.subscription subscription_id
+
+    subscription&.delete
+
+    topic.subscribe subscription_id, message_ordering: true
+
+    puts "Pull subscription #{subscription_id} created with message ordering."
+  end
+end

data/lib/trabox/metric.rb

@@ -11,7 +11,7 @@ module Trabox
   # - publish_event_error_count: イベントのパブリッシュに失敗した数
   # - update_event_record_error_count: パブリッシュしたイベントのカラム更新に失敗した数
   module Metric
-    NAMESPACE = ENV.fetch('METRIC_NAMESPACE', 'trabox')
+    NAMESPACE = ENV.fetch('TRABOX_METRIC_NAMESPACE', 'trabox')
     LOG_PREFIX = '[metric]'
     SERVICE_OK = Datadog::Statsd::OK
     SERVICE_CRITICAL = Datadog::Statsd::CRITICAL

data/lib/trabox/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Trabox
-  VERSION = '0.1.1'
+  VERSION = '0.1.3'
 end

metadata

@@ -1,85 +1,111 @@
 --- !ruby/object:Gem::Specification
 name: trabox
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - kosay
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-06 00:00:00.000000000 Z
+date: 2025-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dogstatsd-ruby
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '5.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '5.5'
 - !ruby/object:Gem::Dependency
   name: google-cloud-pubsub
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.13'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.13'
 - !ruby/object:Gem::Dependency
   name: mysql2
   requirement: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.5.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.5.4
 - !ruby/object:Gem::Dependency
   name: optparse
   requirement: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 6.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 6.0.0
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
 description: Transactional-Outbox for Rails
 email:
 - ekr59uv25@gmail.com
@@ -132,14 +158,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
 summary: Transactional-Outbox for Rails