trabox 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2dfd087c02a6876a14092f0c4a98a1d3769ddfd07311a19fb144d631f0ef23ac
-  data.tar.gz: f2f76599e4c55ee53db897dbf024af024b2edb5d9ee45f37518be50b12f92d67
+  metadata.gz: e7d6e1156090efc8e33e9618f6f449dc7363d67e58aff81324dc7300ab4d644a
+  data.tar.gz: b898fedf626581cee69767ea4f2a810e3fc242e6a6d955d6c0f284ace31d779c
 SHA512:
-  metadata.gz: af18284f3f67a580d69d03d17027113435bbd323e948d26d73d3f58ace23494a10f495abbff0b87af535cc551b7d2f6c756e1d614721d25007791afd3bb058d9
-  data.tar.gz: 93a506e52fc94ad7f075c05416997e74ae3a3315da95b21175676c1c81b0488c736893a7066deb367aeb0b2a1cc5fe6f6730141a5bb098be23ecb2139255572d
+  metadata.gz: e22b0f8227e22ac12f5605671ffbd030e9fbc1bf30b38c38194e2f8e6936b8dc6844b09078ea7e3c648e265d0b04c7f0faeb5636765a5f66515d9dbf11b29eb3
+  data.tar.gz: b47485d03057b4781b4dafd4fd9cf6668814ee58141c253f5b206a7402027cf925d0e676bc2c17e0c8d817c8878ef8516a548f724a217d231bb5abd34dbd1d48

data/README.md

@@ -1,59 +1,193 @@
 # Trabox
 
-[日本語](README.ja.md)
+\[[Japanese](README.ja.md)]\[[English](README.md)]
 
 Transactional-Outbox for Rails.
 
+![](./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**
 
 - Google Cloud Pub/Sub
 
+## Requirements
+
+- Ruby 2.6+
+- Rails 6.0+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'trabox'
+```
+
+And then execute:
+
+```bash
+bundle install
+bin/rails g trabox:configure
+```
+
+This will generate config file `config/initializers/trabox.rb`.
+
+**Optional**:
+
+```bash
+bundle binstubs trabox
+```
+
 ## Usage
 
-### Create outbox tables
+### 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
 ```
 
-### Run
+### Running relayer
 
 ```bash
 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
 ```
 
-How to use my plugin.
+## Metrics
 
-## Installation
+The default namespace of metrics is `trabox`.  
+The namespace can be changed with `TRABOX_METRIC_NAMESPACE` environment variable.
 
-Add this line to your application's Gemfile:
+| 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               |
 
-```ruby
-gem 'trabox'
-```
+### Health check
 
-And then execute:
+| command   | metric name             |
+| --------- | ----------------------- |
+| relay     | relay.service.check     |
+| subscribe | subscribe.service.check |
+
+## Sequence diagram
+
+![](./docs/images/sequence-diagram.svg)
+
+## Contributing
+
+Bug reports and pull requests are welcome.
+
+## Development
+
+### Install gems
 
 ```bash
 bundle install
-bin/rails g trabox:configure
 ```
 
-This will generate config file `config/initializers/trabox.rb`.
+### Start mysql / pubsub emulator
 
-**Optional**:
+```bash
+docker-compose up
+```
+
+**setup db**
 
 ```bash
-bundle binstubs trabox
+cd spec/rails_app
+bin/rails db:setup
 ```
 
-## Contributing
+**create topic / subscribe**
 
-Contribution directions go here.
+```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/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trabox
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - kosay
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-08 00:00:00.000000000 Z
+date: 2025-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dogstatsd-ruby
@@ -82,9 +82,6 @@ dependencies:
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '6.0'
     - - ">="
       - !ruby/object:Gem::Version
         version: 6.0.0
@@ -92,12 +89,23 @@ dependencies:
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '6.0'
     - - ">="
       - !ruby/object:Gem::Version
         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
@@ -157,7 +165,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !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