mysql_replicator 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1fc2f85268cd0a2187b97a8a62761ddaec7730c8d019fcb02b154600fbe00ddb
+  data.tar.gz: 30977b5f6c98d581c73733b9d9c683802935079b1396b3bb01cfecc8ed140486
+SHA512:
+  metadata.gz: b8ec42a9aa2f9fd13b765662777d9f3a68ea6a2551cf56bbeb52402a49a3b29e7b97a4f10971b97547133cd6093091c18271ac0a1ad05cb277db9deb3682d914
+  data.tar.gz: 94c2da74bc3eff4045590a6e30d9de8b2b38947d191fb779de5eaeb911819eeb89a9b3f0087cd1cb3e18af3239b24eb8092470feb3c6ee4f49d2e4f6195113b9

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,79 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/ArgumentAlignment:
+  Enabled: false
+
+Layout/EmptyLineAfterMagicComment:
+  Enabled: false
+
+Layout/LeadingCommentSpace:
+  Enabled: false
+
+Layout/LineLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/BlockNesting:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Style/BitwisePredicate:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/FormatStringToken:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false
+
+Style/OptionalBooleanParameter:
+  Enabled: false
+
+Style/RescueStandardError:
+  Enabled: false
+
+Style/StringConcatenation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: single_quotes
+
+Style/UnpackFirst:
+  Enabled: false
+
+Style/WordArray:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-08-11
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 yo_waka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,115 @@
+# MySQL Replicator
+
+`MysqlReplicator` gem is a library for processing MySQL Binlog events using the MySQL replication protocol.
+
+And also, this is lightweight because only depend on the Ruby standard library.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add mysql_replicator
+```
+
+You can of course add a gem call in your Gemfile yourself.
+
+```bash
+gem 'mysql_replicator'
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install mysql_replicator
+```
+
+## Usage
+
+```rb
+# Custom logger available
+MysqlReplicator.logger = your_custom_logger
+
+# Connect to MySQL server, and start to handle replication event
+MysqlReplicator.run(
+  host: 'your_mysql_host', # default localhost
+  port: 3307,              # default 3306
+  user: 'username',        # default root
+  password: 'password',    # default empty string
+  database: 'test'         # default empty string
+) do |binlog_event|
+    # write code to process binlog event
+
+    puts binlog_event[:timestamp]
+    # => 2025-12-01 12:00:00
+
+    puts binlog_event[:event_type]
+    # => :WRITE_ROWS
+
+    puts binlog_event[:execution]
+    # => {
+    #   table_id: 10,
+    #   flags: 0,
+    #   extra_data_length: 0,
+    #   column_count: 2,
+    #   rows: [
+    #     {
+    #        ordinal_position: 1,
+    #        data_type: 'int',
+    #        column_name: 'id',
+    #        value: 1,
+    #        primary_key: true
+    #     },
+    #     {
+    #        ordinal_position: 2,
+    #        data_type: 'varchar',
+    #        column_name: 'name',
+    #        value: 'alice',
+    #        primary_key: false
+    #     }
+    #   ]
+    # }
+  end
+```
+
+## Development
+
+Start MySQL server.
+```
+$ docker compose up
+```
+
+Start MysqlReplicator to check if local code works.
+```rb
+irb(main):001> MysqlReplicator.run(database: 'test') { |evt| puts evt }
+```
+
+Submit sample DDL and query to MySQL server.
+Check `spec/supports/sql`.
+
+Run spec for test.
+```
+$ bundle exec rspec
+```
+
+Run rubocop for linter.
+```
+$ bundle exec rubocop
+```
+
+Run steep for type check.
+```
+$ bundle exec steep check
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/waka/mysql_replicator. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/waka/mysql_replicator/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the MysqlReplicator project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/waka/mysql_replicator/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/Steepfile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+D = Steep::Diagnostic
+
+target :lib do
+  signature 'sig'
+  ignore_signature 'sig/test'
+
+  check 'lib' # Directory name
+
+  library 'bigdecimal'
+  library 'digest'
+  library 'logger'
+  library 'openssl'
+  library 'socket'
+  library 'stringio'
+
+  configure_code_diagnostics(D::Ruby.strict)
+  configure_code_diagnostics do |hash|
+    hash[D::Ruby::UnannotatedEmptyCollection] = :information
+  end
+end

data/docker-compose.yml

@@ -0,0 +1,13 @@
+services:
+  mysql:
+    image: mysql:8.0
+    environment:
+      - MYSQL_ROOT_PASSWORD=root
+    ports:
+      - "3306:3306"
+    volumes:
+      - mysql_data:/var/lib/mysql:delegated
+
+volumes:
+  mysql_data:
+    driver: local

data/lib/mysql_replicator/binlog_client.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module MysqlReplicator
+  # Binlog handler using MySQL Replication Protocol
+  class BinlogClient
+    # @rbs @connection: MysqlReplicator::Connection
+    # @rbs @server_id: Integer
+    # @rbs @checksum_type: String?
+    # @rbs @event_listener: ^(MysqlReplicator::Binlogs::EventParser::binlogEvent) -> untyped | nil
+
+    # @rbs! attr_reader connection: MysqlReplicator::Connection
+    attr_reader :connection
+
+    # @rbs connection: MysqlReplicator::Connection
+    # @rbs server_id: Integer
+    # @rbs return void
+    def initialize(connection, server_id = 1001)
+      @connection = connection
+      @server_id = server_id
+      @checksum_type = nil
+    end
+
+    # @rbs &block: { (MysqlReplicator::Binlogs::EventParser::binlogEvent) -> untyped | nil }
+    # @rbs return: void
+    def on(&block)
+      @event_listener = block
+    end
+
+    # @rbs return: void
+    def start_replication
+      @connection.connect unless @connection.connected?
+
+      binlog_info = master_status
+      binlog_file = binlog_info[:file]
+      binlog_position = binlog_info[:position]
+
+      configure_binlog_checksum if @checksum_type.nil?
+      register_as_slave
+      start_binlog_dump(binlog_file, binlog_position)
+
+      begin
+        handle_binlog_events
+      rescue Interrupt
+        stop_replication
+      rescue => e
+        MysqlReplicator::Logger.error \
+          "Unexpected error: #{e.message},\n" \
+          "Backtrace: #{e.backtrace.first(5).join("\n")}"
+
+        stop_replication
+      end
+    end
+
+    # @rbs return: void
+    def stop_replication
+      @connection.flush_socket_buffer
+      unregister_as_slave
+      @connection.close
+    end
+
+    # @rbs return: { file: String, position: Integer }
+    def master_status
+      result = @connection.query('SHOW MASTER STATUS')
+      row = result[:rows][0]
+      { file: row[:file].to_s, position: row[:position].to_i }
+    end
+
+    # @rbs return: void
+    def register_as_slave
+      @connection.reset_sequence_id
+
+      # Payload of COM_REGISTER_SLAVE packet
+      payload = [0x15].pack('C')
+      # Server ID (4 bytes)
+      payload += [@server_id].pack('V')
+      # Hostname (empty string but properly formatted)
+      hostname = ''
+      payload += [hostname.length].pack('C') + hostname
+      # Username (empty string but properly formatted)
+      username = ''
+      payload += [username.length].pack('C') + username
+      # Password (empty string but properly formatted)
+      password = ''
+      payload += [password.length].pack('C') + password
+      # MySQL port
+      payload += [@connection.port].pack('V')
+      # Replication rank = 0 (unused)
+      payload += [0].pack('V')
+      # Master ID = 0 (unused)
+      payload += [0].pack('V')
+
+      @connection.send_packet(payload)
+
+      response = @connection.read_packet
+      if response[:payload][0].unpack('C')[0] != 0x00
+        raise MysqlReplicator::Error,
+          'Failed to register as slave ' \
+          "error code = #{response[:payload][1, 2].unpack('v')[0]}, " \
+          "error message = #{response[:payload][9..]}"
+      end
+
+      MysqlReplicator::Logger.info 'Successfully registered as slave'
+    end
+
+    # @rbs return: void
+    def unregister_as_slave
+      @connection.reset_sequence_id
+
+      # Payload of COM_UNREGISTER_SLAVE packet
+      payload = [0x1B].pack('C')
+      # Connection ID (4 bytes)
+      payload += [@connection.connection_id].pack('V')
+
+      @connection.send_packet(payload)
+
+      response = @connection.read_packet
+      if response[:payload][0].unpack('C')[0] != 0x00
+        raise MysqlReplicator::Error,
+          'Failed to unregister as slave ' \
+          "error code = #{response[:payload][1, 2].unpack('v')[0]}, " \
+          "error message = #{response[:payload][9..]}"
+      end
+
+      MysqlReplicator::Logger.info 'Successfully unregistered as slave'
+    end
+
+    # @rbs return: void
+    def configure_binlog_checksum
+      result = @connection.query('SHOW VARIABLES LIKE "binlog_checksum"')
+      @checksum_type = result[:rows][0][:value]
+
+      case @checksum_type
+      when 'NONE'
+        # No checksum
+        MysqlReplicator::Logger.debug 'Set binlog checksum to NONE'
+      when 'CRC32'
+        @connection.query('SET @master_binlog_checksum = "CRC32"')
+        MysqlReplicator::Logger.debug 'Set binlog checksum to CRC32'
+      else
+        raise MysqlReplicator::Error, "Unknown binlog checksum type: #{@checksum_type}"
+      end
+    end
+
+    # @rbs binlog_file: String
+    # @rbs binlog_position: Integer
+    # @rbs return: void
+    def start_binlog_dump(binlog_file, binlog_position)
+      @connection.reset_sequence_id
+
+      # Payload of COM_BINLOG_DUMP packet
+      payload = [0x12].pack('C')
+      # Binlog position (4 bytes)
+      payload += [Integer(binlog_position)].pack('V')
+      # Flags (2 bytes)
+      payload += [0].pack('v')
+      # Slave server ID (4 bytes)
+      payload += [@server_id].pack('V')
+      # Binlog filename
+      payload += binlog_file
+
+      @connection.send_packet(payload)
+
+      MysqlReplicator::Logger.info \
+        "Started binlog dump from #{binlog_file} at position #{binlog_position}"
+    end
+
+    # @rbs return: void
+    def handle_binlog_events
+      event_parser = MysqlReplicator::Binlogs::EventParser.new
+
+      loop do
+        packet = @connection.read_packet
+        payload = packet[:payload]
+
+        first_byte = payload[0].unpack('C')[0]
+
+        case first_byte
+        when 0x00
+          binlog_event = event_parser.execute(payload[1..], @connection, @checksum_type == 'CRC32')
+
+          case binlog_event[:event_type]
+          when :QUERY, :WRITE_ROWS, :UPDATE_ROWS, :DELETE_ROWS
+            @event_listener&.call(binlog_event)
+          end
+          MysqlReplicator::Logger.debug "Binlog event: #{binlog_event}"
+        when 0xFF
+          MysqlReplicator::Logger.error \
+            "Binlog event error: #{payload[1, 2].unpack('v')[0]} - #{payload[3..]}"
+          break
+        when 0xFE
+          MysqlReplicator::Logger.error 'Received EOF packet - binlog stream ended'
+          break
+        else
+          MysqlReplicator::Logger.error "Unexpected packet type: 0x#{first_byte.to_s(16)}"
+          break
+        end
+      end
+    end
+  end
+end