mysql2-aws_rds_iam 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 656c485ac1f6eae9f1d5e98ae78372181954769f32058ac1c9084f8f1bbe2a4c
+  data.tar.gz: a0fcb35212956975bdb0e3fa4908e44eefe0bac68db5324c1e906c4470e7c5f1
+SHA512:
+  metadata.gz: 047445c597981ce9a02af12665f1309962b24f94f9e46e95b2000c32d893ac0ad82f547f588788294c6cd2ce8be30aacb0a9cfe9e7adf0081439d4a841b2af0f
+  data.tar.gz: 5c10dc7fc890d1e825c308a5cf309e66043da0e938c836826cccadf718e762f8d82a083d9857a024995857a641378259a611f3605d9934570937a602efc4fc4d

data/.yardopts

@@ -0,0 +1,5 @@
+--markup markdown
+--markup-provider commonmarker
+--no-private
+-
+*.md

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased](https://github.com/haines/pg-aws_rds_iam/compare/v0.1.0...HEAD)
+
+No notable changes.
+
+## [0.1.0](https://github.com/haines/pg-aws_rds_iam/compare/191a63e3c0222ac05bf06faaa496da954e352bbb...v0.1.0) - 2024-01-14
+
+### Added
+* `Mysql2::AwsRdsIam` is an extension of [mysql2](https://github.com/brianmario/mysql2) gem that adds support of [IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html) when connecting to MySQL in Amazon RDS.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Taras Shpachenko
+
+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,127 @@
+# Mysql2::AwsRdsIam
+
+[![Gem](https://img.shields.io/gem/v/mysql2-aws_rds_iam)](https://rubygems.org/gems/mysql2-aws_rds_iam)
+ 
+![CI](https://img.shields.io/github/actions/workflow/status/floor114/mysql2-aws_rds_iam/ci.yml)
+
+`Mysql2::AwsRdsIam` is an extension of [mysql2](https://github.com/brianmario/mysql2) gem that adds support of [IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html) when connecting to MySQL in Amazon RDS.
+
+This gem is a powerful tool that enables seamless connection to MySQL databases using the [mysql2](https://github.com/brianmario/mysql2) gem. It leverages the dynamic password generation feature of AWS RDS [IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html) for enhanced security and easy password management.
+
+
+## Installation
+
+Install manually:
+
+```console
+$ gem install mysql2-aws_rds_iam
+```
+
+or with Bundler:
+
+```console
+$ bundle add mysql2-aws_rds_iam
+```
+
+## Usage
+
+To leverage [IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html) for your database connections, follow these steps:
+
+1. Enable [IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html) for your database through AWS 
+2. Add IAM credentials to your application.
+3. Set up your application to generate authentication tokens.
+
+
+### Application configurations
+
+The default algorithm is `Mysql2::AwsRdsIam`'s [default authentication token generator](https://github.com/floor114/mysql2-aws_rds_iam/blob/main/lib/mysql2/aws_rds_iam/auth_token/generator.rb). Credentials and region are extracted using [aws-sdk-rds](https://github.com/aws/aws-sdk-ruby/tree/version-3/gems/aws-sdk-rds) configurations.
+
+
+#### Apply msql2 patch
+To connect to your MySQL database, you need to create initializer file that applies the patch:
+
+  ```ruby
+  # config/initializers/tcc_rds_iam_auth.rb
+
+  Tcc::RdsIamAuth.apply_patch
+
+  ```
+
+#### Configure `database.yml`
+New rds_iam_auth_host parameter must be added to the database.yml file:
+
+  ```yaml
+  production:
+    # ...
+    aws_rds_iam_auth: true
+  ```
+
+#### Custom token generator
+If the default generator doesn't meet your needs, you can create a custom one
+
+  ```ruby
+  # config/initializers/tcc_rds_iam_auth.rb
+
+  Mysql2::AwsRdsIam.auth_token_registry.add(:custom, ->(host, port, username) { 'your custom logic' })
+
+  ```
+
+and specify it in `database.yml`
+
+  ```yaml
+  production:
+    # ...
+    aws_rds_iam_auth: true
+    aws_rds_iam_auth_token_generator: custom
+  ```
+
+`Mysql2::AwsRdsIam.auth_token_registry` accepts two parameters:
+1. Generator name. The same name should be specified in `database.yml`
+2. Object that responds to `call` method and accepts 3 arguments (`host, port, username`) specified in `database.yml`.
+
+##### Possible generator types
+* Lambda
+  ```ruby
+  Mysql2::AwsRdsIam.auth_token_registry.add(:custom, ->(host, port, username) { 'your custom logic' })
+
+  ```
+* Generator instance
+  ```ruby
+  class CustomGenerator
+    def call(host, port, username)
+      GenerateMyCode
+    end
+  end
+
+  Mysql2::AwsRdsIam.auth_token_registry.add(:custom, CustomGenerator.new)
+
+  ```
+* Generator class
+  ```ruby
+  class CustomGenerator
+    def self.call(host, port, username)
+      GenerateMyCode
+    end
+  end
+
+  Mysql2::AwsRdsIam.auth_token_registry.add(:custom, CustomGenerator)
+
+  ```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake` to run the tests and linter. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/floor114/mysql2-aws_rds_iam. 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/[USERNAME]/mysql2-aws_rds_iam/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).
+
+## Special Thanks
+
+Inspired by [Andrew Haines'](https://github.com/haines) PG version [pg-aws_rds_iam](https://github.com/haines/pg-aws_rds_iam)

data/lib/mysql2/aws_rds_iam/auth_token/factory.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Mysql2
+  module AwsRdsIam
+    module AuthToken
+      class Factory
+        DEFAULT_GENERATOR = :default
+
+        def self.call(generator, host, port, username)
+          AwsRdsIam.auth_token_registry.fetch(generator&.to_sym || DEFAULT_GENERATOR).call(
+            host: host,
+            port: port,
+            username: username
+          )
+        end
+      end
+    end
+  end
+end

data/lib/mysql2/aws_rds_iam/auth_token/generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Mysql2
+  module AwsRdsIam
+    module AuthToken
+      class Generator
+        def initialize
+          aws_config = Aws::RDS::Client.new.config
+
+          @generator = Aws::RDS::AuthTokenGenerator.new(credentials: aws_config.credentials)
+          @region = aws_config.region
+        end
+
+        def call(host:, port:, username:)
+          generator.auth_token(
+            region: region,
+            endpoint: "#{host}:#{port}",
+            user_name: username.to_s
+          )
+        end
+
+        private
+
+        attr_reader :generator, :region
+      end
+    end
+  end
+end

data/lib/mysql2/aws_rds_iam/auth_token/registry.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Mysql2
+  module AwsRdsIam
+    module AuthToken
+      class Registry < Hash
+        def initialize
+          add(:default, Generator.new)
+
+          super
+        end
+
+        def add(name, generator)
+          self[name] = generator
+        end
+      end
+    end
+  end
+end

data/lib/mysql2/aws_rds_iam/client_extension.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Mysql2
+  module AwsRdsIam
+    module ClientExtension
+      def initialize(opts = {})
+        opts = opts.dup
+        aws_rds_iam_auth = opts.delete(:aws_rds_iam_auth)
+
+        if aws_rds_iam_auth
+          raise Errors::ReconnectConfigEnabledError if opts[:reconnect]
+
+          username = opts[:username]
+          host = opts[:host]
+          port = opts[:port]
+
+          raise Errors::UsernameNotFoundError if username.nil?
+          raise Errors::HostNotFoundError if host.nil?
+
+          opts.delete(:password)
+
+          aws_rds_iam_auth_token_generator = opts.delete(:aws_rds_iam_auth_token_generator)
+
+          opts[:password] = AuthToken::Factory.call(aws_rds_iam_auth_token_generator, host, port, username)
+          opts[:enable_cleartext_plugin] = true
+        end
+
+        super(opts)
+      end
+    end
+  end
+end

data/lib/mysql2/aws_rds_iam/errors.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Mysql2
+  module AwsRdsIam
+    module Errors
+      class Error < StandardError; end
+
+      class Mysql2ClientNotFoundError < Error
+        def initialize
+          super('Could not find class or method when patching Mysql2::Client. Please investigate.')
+        end
+      end
+
+      class ReconnectConfigEnabledError < Error
+        def initialize
+          super('reconnect config must be false if using AWS RDS IAM authentication.')
+        end
+      end
+
+      class UsernameNotFoundError < Error
+        def initialize
+          super('username must be present.')
+        end
+      end
+
+      class HostNotFoundError < Error
+        def initialize
+          super('host must be present.')
+        end
+      end
+    end
+  end
+end

data/lib/mysql2/aws_rds_iam/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Mysql2
+  module AwsRdsIam
+    VERSION = '0.1.0'
+  end
+end

data/lib/mysql2/aws_rds_iam.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'aws-sdk-rds'
+require 'mysql2'
+require 'zeitwerk'
+
+loader = Zeitwerk::Loader.for_gem_extension(Mysql2)
+loader.setup
+
+module Mysql2
+  module AwsRdsIam
+    def self.auth_token_registry
+      @auth_token_registry ||= AuthToken::Registry.new
+    end
+
+    def self.apply_patch
+      const = begin
+        Object.const_get('Mysql2::Client')
+      rescue StandardError
+        raise Errors::Mysql2ClientNotFoundError
+      end
+
+      begin
+        const.instance_method(:initialize)
+      rescue StandardError
+        raise Errors::Mysql2ClientNotFoundError
+      end
+
+      const.prepend(ClientExtension)
+    end
+  end
+
+  AwsRdsIam.apply_patch
+end

data/lib/mysql2-aws_rds_iam.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'mysql2/aws_rds_iam'

data/mysql2-aws_rds_iam.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'lib/mysql2/aws_rds_iam/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'mysql2-aws_rds_iam'
+  spec.version = Mysql2::AwsRdsIam::VERSION
+  spec.authors = ['Taras Shpachenko']
+  spec.email = ['taras.shpachenko@gmail.com']
+
+  spec.summary = 'AWS RDS IAM authentication for MySQL'
+  spec.description = 'Mysql2::AwsRdsIam is an extension of mysql2 gem that adds support ' \
+                     'of IAM authentication when connecting to MySQL in Amazon RDS.'
+  spec.homepage = 'https://github.com/floor114/mysql2-aws_rds_iam'
+  spec.license = 'MIT'
+
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['bug_tracker_uri'] = "#{spec.homepage}/issues"
+  spec.metadata['documentation_uri'] = "https://rubydoc.info/gems/mysql2-aws_rds_iam/#{Mysql2::AwsRdsIam::VERSION}"
+
+  spec.files = Dir[
+    'lib/**/*.rb',
+    '.yardopts',
+    'CHANGELOG.md',
+    'LICENSE.txt',
+    'mysql2-aws_rds_iam.gemspec',
+    'README.md'
+  ]
+  spec.require_paths = ['lib']
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency 'aws-sdk-rds', '~> 1'
+  spec.add_dependency 'mysql2'
+  spec.add_dependency 'zeitwerk', '~> 2'
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: mysql2-aws_rds_iam
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Taras Shpachenko
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-01-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-rds
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: Mysql2::AwsRdsIam is an extension of mysql2 gem that adds support of
+  IAM authentication when connecting to MySQL in Amazon RDS.
+email:
+- taras.shpachenko@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/mysql2-aws_rds_iam.rb
+- lib/mysql2/aws_rds_iam.rb
+- lib/mysql2/aws_rds_iam/auth_token/factory.rb
+- lib/mysql2/aws_rds_iam/auth_token/generator.rb
+- lib/mysql2/aws_rds_iam/auth_token/registry.rb
+- lib/mysql2/aws_rds_iam/client_extension.rb
+- lib/mysql2/aws_rds_iam/errors.rb
+- lib/mysql2/aws_rds_iam/version.rb
+- mysql2-aws_rds_iam.gemspec
+homepage: https://github.com/floor114/mysql2-aws_rds_iam
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/floor114/mysql2-aws_rds_iam
+  source_code_uri: https://github.com/floor114/mysql2-aws_rds_iam
+  changelog_uri: https://github.com/floor114/mysql2-aws_rds_iam/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/floor114/mysql2-aws_rds_iam/issues
+  documentation_uri: https://rubydoc.info/gems/mysql2-aws_rds_iam/0.1.0
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: AWS RDS IAM authentication for MySQL
+test_files: []