trabox 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2dfd087c02a6876a14092f0c4a98a1d3769ddfd07311a19fb144d631f0ef23ac
-  data.tar.gz: f2f76599e4c55ee53db897dbf024af024b2edb5d9ee45f37518be50b12f92d67
+  metadata.gz: 10134c8640681cb8e318e0eae8c0d2e5bb9a2b35a820ab2f753a48718baa773f
+  data.tar.gz: c4d99b320e40138b12af2fa0773548ef0b2b835533e1a6c8bd95f6218203f9bf
 SHA512:
-  metadata.gz: af18284f3f67a580d69d03d17027113435bbd323e948d26d73d3f58ace23494a10f495abbff0b87af535cc551b7d2f6c756e1d614721d25007791afd3bb058d9
-  data.tar.gz: 93a506e52fc94ad7f075c05416997e74ae3a3315da95b21175676c1c81b0488c736893a7066deb367aeb0b2a1cc5fe6f6730141a5bb098be23ecb2139255572d
+  metadata.gz: 48ef456ee8180a84c31143dce056ec3dbda8eafd855b3ff46c5248a95d7d838c3f71a797dc9267cd89693802588fd5edfc9b1deb08fc5e5a318f599efaf6eda3
+  data.tar.gz: 4b315ed9f8ebcde7105f56ed0449b3868dccf5c9d2ebe0076213a9cfb00f75d08896b9ded3e3c38d7f426fd994a5994aa2e2f9592296bc0ba077ccda661b3e8a

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 3.2+
+- Rails 7.2+
+
+## 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/commands/relay.rb

@@ -38,7 +38,7 @@ module Trabox
           rescue StandardError => e
             Rails.logger.error e
 
-            ActiveRecord::Base.clear_all_connections!
+            ActiveRecord::Base.connection_handler.clear_all_connections!(:all)
 
             Metric.service_check('relay.service.check', Metric::SERVICE_CRITICAL)
           end

data/lib/trabox/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: trabox
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - kosay
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-08 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dogstatsd-ruby
@@ -82,22 +81,30 @@ dependencies:
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '6.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.0.0
+        version: 7.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.2.0
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.0'
-    - - ">="
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.0.0
+        version: '2.5'
 description: Transactional-Outbox for Rails
 email:
 - ekr59uv25@gmail.com
@@ -142,7 +149,6 @@ homepage: https://github.com/sarub0b0/trabox
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -150,15 +156,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Transactional-Outbox for Rails
 test_files: []