# floor114/mysql2-aws_rds_iam architecture

> Architecture diagram of the GitHub repository floor114/mysql2-aws_rds_iam, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/floor114/mysql2-aws_rds_iam
- Repository: https://github.com/floor114/mysql2-aws_rds_iam

## Overview

##### Project type and purpose
- Type: An open-source Ruby gem (library) that patches the `mysql2` client to support AWS RDS IAM authentication.
- Purpose: When you call `Mysql2::Client.new` with `aws_rds_iam_auth: true`, the gem intercepts the connection, generates a short-lived auth token via AWS SDK, and then connects to MySQL on RDS using that token.

##### Main components
a. Consumer (Ruby application or script)
- Your Rails or Ruby code that does `require 'mysql2/aws_rds_iam'` and `Mysql2::Client.new(...)`.
b. mysql2-aws_rds_iam gem
- ClientExtension – monkey-patches `Mysql2::Client` to detect `aws_rds_iam_auth`.
- AuthToken Registry – holds token generators keyed by name.
- Default Generator – uses `Aws::RDS::AuthTokenGenerator` (from aws-sdk-rds) to build tokens.
- ExpirableToken – wraps the raw token with expiry logic.
- Factory – orchestrates creation of `ExpirableToken` via selected generator.
- Errors – custom exception types.
c. External dependency
- aws-sdk-rds – the AWS Ruby SDK that actually talks to AWS STS/RDS to retrieve a signed auth token.
d. External service
- Amazon RDS MySQL instance with IAM authentication enabled.

##### Relationships and interactions
1) Application invokes `Mysql2::Client.new` with `aws_rds_iam_auth: true`.
2) ClientExtension intercepts initialization and calls `AuthTokenFactory.build(host, port, username)`.
3) Factory looks up the chosen generator in `AuthTokenRegistry`.
4) DefaultGenerator (or custom) calls into aws-sdk-rds’s `AuthTokenGenerator.generate` to retrieve a presigned URL/token.
5) The raw token is wrapped into an `ExpirableToken` object.
6) ClientExtension supplies the token as the password parameter to the underlying mysql2 C extension.
7) mysql2 C extension makes the TCP handshake to the Amazon RDS endpoint using the token, returning a client connection.

##### Architectural patterns and principles
- Monkey-patch / extension pattern: Patches `Mysql2::Client` at runtime.
- Registry pattern: `AuthTokenRegistry` for pluggable token generators.
- Factory pattern: `AuthTokenFactory` to decouple generator lookup and invocation.
- Single Responsibility: Each module (Errors, Version, ClientExtension, Registry, Generator) has a well-defined role.
- Open-Source best practice: clear separation of core logic vs. extension points for customization.

##### Putting it all together
- Layout left to right or top to bottom: Application → Gem internals → AWS SDK → RDS.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    App["Consumer Application"]:::frontend

    subgraph "Gem: mysql2-aws_rds_iam"
        direction TB
        EP["Entry Point"]:::gem
        NS["Namespace Loader"]:::gem
        Ver["Version"]:::gem
        Err["Errors"]:::gem
        CE["ClientExtension"]:::gem
        Reg["AuthTokenRegistry"]:::gem
        Fac["AuthTokenFactory"]:::gem
        DefGen["DefaultGenerator"]:::gem
        Token["ExpirableToken"]:::gem
    end

    aws["aws-sdk-rds"]:::externalDep
    subgraph "AWS Services"
        RDS["Amazon RDS MySQL (IAM)"]:::service
    end

    %% Connections
    App -->|"require & Mysql2::Client.new(aws_rds_iam_auth: true)"| EP
    EP -->|"loads namespace" | NS
    NS -->|"monkey-patch client" | CE
    CE -->|"build(host,port,user)"| Fac
    Fac -->|"lookup generator"| Reg
    Reg -->|"returns generator"| DefGen
    DefGen -->|"generate(host,port,user)"| aws
    aws -->|"returns presigned token"| DefGen
    DefGen -->|"wrap(token)"| Token
    Token -->|"return ExpirableToken"| Fac
    Fac -->|"provides token"| CE
    CE -->|"connect(token)"| RDS

    %% Click Events
    click EP "https://github.com/floor114/mysql2-aws_rds_iam/blob/main/lib/mysql2-aws_rds_iam.rb"
    click NS "https://github.com/floor114/mysql2-aws_rds_iam/blob/main/lib/mysql2/aws_rds_iam.rb"
    click Ver "https://github.com/floor114/mysql2-aws_rds_iam/blob/main/lib/mysql2/aws_rds_iam/version.rb"
    click Err "https://github.com/floor114/mysql2-aws_rds_iam/blob/main/lib/mysql2/aws_rds_iam/errors.rb"
    click CE "https://github.com/floor114/mysql2-aws_rds_iam/blob/main/lib/mysql2/aws_rds_iam/client_extension.rb"
    click Reg "https://github.com/floor114/mysql2-aws_rds_iam/blob/main/lib/mysql2/aws_rds_iam/auth_token/registry.rb"
    click Fac "https://github.com/floor114/mysql2-aws_rds_iam/blob/main/lib/mysql2/aws_rds_iam/auth_token/factory.rb"
    click DefGen "https://github.com/floor114/mysql2-aws_rds_iam/blob/main/lib/mysql2/aws_rds_iam/auth_token/generator.rb"
    click Token "https://github.com/floor114/mysql2-aws_rds_iam/blob/main/lib/mysql2/aws_rds_iam/auth_token/expirable_token.rb"
    click aws "https://github.com/floor114/mysql2-aws_rds_iam/blob/main/mysql2-aws_rds_iam.gemspec"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085
    classDef gem fill:#d4edda,stroke:#155724
    classDef externalDep fill:#fff3cd,stroke:#856404
    classDef service fill:#f8d7da,stroke:#721c24
```
