{"id":16779469,"url":"https://github.com/vvatanabe/dynamomq","last_synced_at":"2026-03-01T16:34:15.569Z","repository":{"id":192902756,"uuid":"687160848","full_name":"vvatanabe/dynamomq","owner":"vvatanabe","description":"Implementing message queueing with Amazon DynamoDB in Go.","archived":false,"fork":false,"pushed_at":"2023-12-26T20:53:00.000Z","size":701,"stargazers_count":35,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-18T17:48:53.975Z","etag":null,"topics":["aws","dynamodb","go","golang","message-queue","queue"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vvatanabe.png","metadata":{"files":{"readme":"README.ja.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-09-04T18:59:15.000Z","updated_at":"2025-05-27T19:01:45.000Z","dependencies_parsed_at":"2023-12-15T10:40:48.567Z","dependency_job_id":"e66189c8-253d-4c17-80b1-4f59fe80a28b","html_url":"https://github.com/vvatanabe/dynamomq","commit_stats":null,"previous_names":["vvatanabe/82f46979","vvatanabe/dynamomq","vvatanabe/go82f46979"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/vvatanabe/dynamomq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vvatanabe%2Fdynamomq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vvatanabe%2Fdynamomq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vvatanabe%2Fdynamomq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vvatanabe%2Fdynamomq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vvatanabe","download_url":"https://codeload.github.com/vvatanabe/dynamomq/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vvatanabe%2Fdynamomq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29974747,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T16:18:32.386Z","status":"ssl_error","status_checked_at":"2026-03-01T16:18:04.258Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","dynamodb","go","golang","message-queue","queue"],"created_at":"2024-10-13T07:30:06.288Z","updated_at":"2026-03-01T16:34:15.552Z","avatar_url":"https://github.com/vvatanabe.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DynamoMQ: Go言語で実装するDynamoDBベースのメッセージキュー\n\n[![Build](https://github.com/vvatanabe/dynamomq/actions/workflows/build.yml/badge.svg)](https://github.com/vvatanabe/dynamomq/actions/workflows/build.yml) [![Go Reference](https://pkg.go.dev/badge/github.com/vvatanabe/dynamomq.svg)](https://pkg.go.dev/github.com/vvatanabe/dynamomq) [![Go Report Card](https://goreportcard.com/badge/github.com/vvatanabe/dynamomq)](https://goreportcard.com/report/github.com/vvatanabe/dynamomq) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=vvatanabe_dynamomq\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=vvatanabe_dynamomq) [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=vvatanabe_dynamomq\u0026metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=vvatanabe_dynamomq) [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=vvatanabe_dynamomq\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=vvatanabe_dynamomq)  [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=vvatanabe_dynamomq\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=vvatanabe_dynamomq) [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=vvatanabe_dynamomq\u0026metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=vvatanabe_dynamomq) [![Bugs](https://sonarcloud.io/api/project_badges/measure?project=vvatanabe_dynamomq\u0026metric=bugs)](https://sonarcloud.io/summary/new_code?id=vvatanabe_dynamomq) [![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=vvatanabe_dynamomq\u0026metric=code_smells)](https://sonarcloud.io/summary/new_code?id=vvatanabe_dynamomq) [![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=vvatanabe_dynamomq\u0026metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=vvatanabe_dynamomq) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=vvatanabe_dynamomq\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=vvatanabe_dynamomq)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg height=\"300\" src=\"https://cacoo.com/diagrams/DjoA2pSKnhCghTYM-192C1.png\"\u003e\n\u003c/p\u003e\n\n[@vvatanabe](https://twitter.com/vvvatanabe)です。Go言語を用いてDynamoDBをストレージに活用したメッセージキューイングのライブラリ、DynamoMQを開発しました。このライブラリは、Go言語でのコンシューマーおよびプロデューサーの実装を支援するSDKと、管理ツールとして機能するCLIを提供します。\n\nこの記事では、DynamoMQの開発動機、提供する機能、CLIやSDKの使用方法、そしてその設計についてご紹介します。\n\nNote: この記事は、[ヌーラボブログリレー2023 for Tech Advent Calendar 2023 – Adventar](https://adventar.org/calendars/8738) の最終日に掲載されたものです。\n\n## Table of Contents\n\n- [DynamoDBの特性とMQのベースにする利点](#DynamoDBの特性とMQのベースにする利点)\n- [既存のAWSキューイングソリューションとの比較](#既存のAWSキューイングソリューションとの比較)\n- [DynamoMQがサポートする機能について](#DynamoMQがサポートする機能について)\n- [DynamoMQのインストール方法](#DynamoMQのインストール方法)\n- [DynamoMQのセットアップ方法](#DynamoMQのセットアップ方法)\n- [DynamoMQの認証とクレデンシャル情報](#DynamoMQの認証とクレデンシャル情報)\n- [DynamoMQ CLIの使用方法](#DynamoMQ-CLIの使用方法)\n- [DynamoMQ SDKの使用方法](#DynamoMQ-SDKの使用方法)\n- [DynamoMQの設計について](#DynamoMQの設計について)\n- [まとめ](#まとめ)\n- [謝辞](#謝辞)\n- [著者](#著者)\n- [ライセンス](#ライセンス)\n\n## DynamoDBの特性とMQのベースにする利点\n\nメッセージキュー（以下、MQ）を用いたシステムは、アプリケーション間でメッセージを非同期に伝達する目的で広く採用されています。これらのシステムでは、高いスループットと信頼性が特に重視されます。このセクションでは、DynamoDBの特性をMQシステムと組み合わせることの利点を考察します。\n\n### DynamoDBの概要\n\nAmazon DynamoDBは、高性能なNoSQLデータベースサービスで、単純なキーバリューストアから複雑なドキュメント型のストアまで、幅広いデータモデルに対応しています。DynamoDBが持つ主な特徴は以下のとおりです。\n\n- **パフォーマンスとスケーラビリティ**: DynamoDBはミリ秒単位で応答可能であり、必要に応じて自動的に読み書きのキャパシティをスケールアップ・ダウンできます。\n- **高可用性と耐久性**: データは自動的に複数の地理的に分散した施設にレプリケーションされるため、高度な可用性と耐久性を実現します。\n- **フルマネージドでサーバーレス**: サーバーの管理や設定に関する手間がかからず、運用コストを削減できます。\n\n参考: [What is Amazon DynamoDB?](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Introduction.html)\n\n### MQとDynamoDBの組み合わせの利点\n\nDynamoDBのこれらの特性をMQシステムに応用することで、以下のようなメリットを享受できます。\n\n1. **スケーラビリティ**: 大量のメッセージを効率的に扱う能力は、MQシステムにとって極めて重要です。DynamoDBのオンデマンドモードにより、需要の変動に応じて容易にリソースを調整できます。\n2. **コスト効率**: オンデマンドモードを利用することで、リソースのオーバープロビジョニングやアンダープロビジョニングのリスクを低減し、コストを抑えることができます。さらに、使用量を予測できる場合にはプロビジョニングモードを選択することで、コストをさらに削減することも可能です。\n3. **信頼性と可用性**: メッセージの喪失はMQにとって致命的です。DynamoDBの高い耐久性と可用性は、メッセージの安全性を保証します。\n4. **柔軟性**: DynamoDBに保存されたメッセージの項目を編集することで、キュー内のメッセージの順序を動的に変更したり、属性を更新したり、メッセージの処理をキャンセルするなど、より柔軟な操作が可能になります。\n\n## 既存のAWSキューイングソリューションとの比較\n\nAWSでは、MQに対して、Amazon SQS、Amazon MQ、そしてKafkaに基づくAmazon MSKなど、複数のソリューションを提供しています。これらのサービスとDynamoMQを比較することで、DynamoMQ独自の利点を考察します。\n\n### Amazon SQSとの比較\n\nAmazon SQSはフルマネージドでサーバーレスなMQサービスであり、大規模な分散アプリケーションにおけるメッセージの非同期処理に広く利用されています。\n\n\u003cins\u003e**スケーラビリティ、コスト効率、信頼性、そして可用性は非常に優れており、筆者の見解としては基本的にAmazon SQSの使用を推奨します。**\u003c/ins\u003e\n\nしかし、Amazon SQSは柔軟性に欠ける面もあります。キューに送信されたメッセージは外部から順序を変更したり、メッセージの属性や項目を更新することができません。また、キュー内のメッセージを参照するには、一度受信する必要があります。これらの制約は、特定の問題に対処する際に調査や復旧作業を困難にすることがあります。\n\n### Amazon MQとの比較\n\nAmazon MQは、Apache ActiveMQやRabbitMQをベースにしたメッセージブローカーサービスで、既存のアプリケーションからの移行を主な目的としています。JMS、AMQP、STOMP、MQTT、OpenWire、WebSocketといった多様なプロトコルをサポートしています。\n\nベースとなるActiveMQやRabbitMQが提供する機能をそのまま利用できるため、Amazon MQは多くの機能を提供しています。しかし、Amazon MQはサーバーレスではないため、セットアップと管理には手間がかかります。\n\n### Amazon MSKとの比較\n\nAmazon MSKは、Apache Kafkaをフルマネージドで提供するサービスで、大量のストリーミングデータ処理に適しています。\n\nMSKはリアルタイムデータストリーミングに特化している一方で、DynamoMQは一般的なメッセージキューイングのニーズに焦点を当てています。また、MSKは高度な設定が可能ですが、それに伴い複雑さとコストが増加する傾向にあります。\n\n### DynamoMQの優位性について\n\nDynamoMQは、DynamoDBのスケーラビリティ、耐久性、そしてサーバーレスという特性を活かし、従来のAWSキューイングソリューションと比較して、メッセージの順序や属性を柔軟に管理できる点、低コストでの運用、そして簡単なセットアップと管理などの優位性を持っています。\n\n## DynamoMQがサポートする機能について\n\nDynamoMQは、MQとして提供すべき主要な機能を備えており、柔軟かつ信頼性の高いシステムの実現を支援します。\n\n### 再配信\n\nメッセージが正常に処理されなかった場合に再配信を行います。これにより、一時的なエラーや処理の遅延に対応し、メッセージが確実に処理される機会を増やします。\n\n### 並列実行\n\n複数のゴルーチンを使用して、メッセージの処理を並行して行います。この機能により、高スループットと効率的なリソース利用が可能になります。\n\n### デッドレターキュー\n\n再配信の最大回数を超えたメッセージをデッドレターキューに移動します。これにより、永続的なエラーを持つメッセージを分離し、後で分析や手動での処理を可能にします。\n\n### グレースフルシャットダウン\n\nコンシューマプロセスのシャットダウン前にメッセージの処理を完了させます。これにより、プロセス終了時に処理中のメッセージが失われることを防ぎます。\n\n### FIFO\n\nFIFO（先入れ先出し）方式でメッセージをキューから取得します。これは、メッセージが送信された順序で処理されることを保証し、順序性が重要なアプリケーションに適しています。\n\n### コンシューマプロセスのスケーリング\n\n複数のコンシューマプロセスを起動し、スケールアウトできます。同じメッセージキューからのメッセージを重複して取得することはありません。これにより、負荷に応じて処理能力を動的に調整できます。\n\n### 可視性タイムアウト\n\n一定期間、すべてのコンシューマによるメッセージの可視性タイムアウトを設定します。これにより、メッセージが処理中に他のコンシューマによって受信されることを防ぎます。\n\n### 遅延キューイング\n\n新しいメッセージの消費者への配信を設定した秒数だけ遅らせる遅延キューイングを提供します。\n\n## DynamoMQのインストール方法\n\nGoのバージョン1.21以上が必要です。\n\n### DynamoMQ CLIのインストール\n\n以下のgo installコマンドを使用して、このパッケージをCLIとしてインストールできます:\n```\n$ go install github.com/vvatanabe/dynamomq/cmd/dynamomq@latest\n```\n\n### DynamoMQ SDKのインストール\n\n以下のgo getコマンドを使用して、このパッケージをSDKとしてインストールできます:\n```\n$ go get -u github.com/vvatanabe/dynamomq@latest\n```\n\n## DynamoMQのセットアップ方法\n\n必要なIAMポリシーとテーブルの作成方法について説明します。\n\n### 必要なIAMポリシーについて\n\n必要なIAMポリシーに関する詳細は、[dynamomq-iam-policy.json](./dynamomq-iam-policy.json) または [dynamomq-iam-policy.tf](./dynamomq-iam-policy.tf) をご覧ください。\n\n### AWS CLIを利用したテーブルの作成方法\n\n以下のコマンドを使用してAWS CLIでテーブルを作成します:\n```sh\naws dynamodb create-table --cli-input-json file://dynamomq-table.json \n```\n[dynamomq-table.json](./dynamomq-table.json) をご覧ください。\n\n### Terraformを利用したテーブルの作成方法\n\n詳細は、[dynamomq-table.tf](./dynamomq-table.tf) をご覧ください。\n\n## DynamoMQの認証とクレデンシャル情報\n\nDynamoMQのCLIとSDKでは、外部の設定ソースから取得されたクレデンシャル情報を用います。設定のためのデフォルトソースは以下の通りです:\n\n### 環境変数\n\n- `AWS_REGION` - AWSリージョンを指定します。\n- `AWS_PROFILE` - 使用するAWSプロファイルを指定します。\n- `AWS_ACCESS_KEY_ID` - AWSアクセスキーを指定します。\n- `AWS_SECRET_ACCESS_KEY` - AWSシークレットキーを指定します。\n- `AWS_SESSION_TOKEN` - 一時的なクレデンシャルのセッショントークンを指定します。\n\n## DynamoMQ CLIの使用方法\n\nDynamoMQ CLIは、DynamoDBベースのMQとやりとりするために一連のコマンドを提供しています。以下に、`dynamomq`で利用可能なコマンドとグローバルフラグを紹介します。\n\n### 利用可能なコマンド一覧\n\n- `completion`: 指定されたシェル用の自動補完スクリプトを生成し、コマンドの利用を容易にします。\n- `delete`: IDを使ってキューからメッセージを削除します。\n- `dlq`: デッドレターキュー（DLQ）の統計を取得し、メッセージ処理の失敗に関する情報を提供します。\n- `enqueue-test`: IDがA-101、A-202、A-303、A-404のテストメッセージをDynamoDBテーブルに送信します。既存の同じIDのメッセージは上書きされます。\n- `fail`: メッセージ処理の失敗をシミュレートし、メッセージをキューに戻します。\n- `get`: IDを使ってDynamoDBテーブルから特定のメッセージを取得します。\n- `help`: 各コマンドに関するヘルプ情報を表示します。\n- `invalid`: スタンダードキューからDLQにメッセージを移動し、手動での確認と修正を行います。\n- `ls`: キュー内の全てのメッセージのIDをリストを最大10要素を表示します。\n- `purge`: DynamoMQテーブルから全てのメッセージを削除し、キューをクリアします。\n- `qstat`: キューの統計情報を取得し、その現在の状態についての概要を提供します。\n- `receive`: キューからメッセージを受信します。\n- `redrive`: DLQからスタンダードキューへメッセージを戻し、再処理します。\n- `reset`: メッセージのシステム情報をリセットします。\n\n### グローバルフラグ\n\n- `--endpoint-url`: 特定のエンドポイントURLを指定してデフォルトのURLを上書きします。\n- `-h`, `--help`: `dynamomq`に関するヘルプ情報を表示します。\n- `--queueing-index-name`: 使用するキューインデックスの名前を指定します（デフォルトは`\"dynamo-mq-index-queue_type-sent_at\"`）。\n- `--table-name`: アイテムを格納するDynamoDBテーブルの名前を定義します（デフォルトは`\"dynamo-mq-table\"`）。\n\n特定のコマンドに関する詳細情報を取得するには、`dynamomq [command] --help`を使用してください。\n\n### インタラクティブモード\n\nDynamoMQ CLIはインタラクティブモードをサポートしています。インタラクティブモードに入るには、サブコマンドを指定せずに`dynamomq`コマンドを実行します。\n\n#### インタラクティブモードで利用可能なコマンド\n\nインタラクティブモードでは、以下のコマンドを提供します:\n\n- `qstat`: キューの統計情報を取得します。\n- `dlq`: デッドレターキュー（DLQ）の統計情報を取得します。\n- `enqueue-test`または`et`: IDがA-101、A-202、A-303、A-404のテストメッセージをDynamoDBテーブルに送信します。既存のメッセージが存在する場合は上書きされます。\n- `purge`: DynamoMQテーブルから全てのメッセージを削除します。\n- `ls`: 最大10要素までの全メッセージIDをリスト表示します。\n- `receive`: キューからメッセージを受信します。\n- `id \u003cid\u003e`: IDを指定して対象のメッセージに対して様々な操作を実行できるようにします:\n  - `sys`: メッセージのシステム情報をJSON形式で表示します。\n  - `data`: 現在のメッセージの`data`部分ををJSONで出力します。\n  - `info`: メッセージに関する全情報をJSON形式で出力します。\n  - `reset`: メッセージのシステム情報をリセットします。\n  - `redrive`: DLQからスタンダードキューへメッセージを戻します。\n  - `delete`: IDを使ってメッセージを削除します。\n  - `fail`: キューに戻されるメッセージの処理失敗をシミュレートします。その後、メッセージは再受信できるようなります。\n  - `invalid`: スタンダードキューからDLQへメッセージを移動します。\n\n## DynamoMQ SDKの使用方法\n\nDynamoMQは、Go言語用のSDKを提供し、コンシューマーとプロデューサーの実装をサポートします。以下に、DynamoMQライブラリを使用するための簡単な例を示します。詳細については[GoDoc](https://pkg.go.dev/github.com/vvatanabe/dynamomq)を参照してください。\n\n### DynamoMQクライアントの設定\n\nDynamoMQの利用を始めるには、まずAWS SDK for Go v2とDynamoMQから必要なパッケージをインポートします。これらは、AWSサービスとDynamoMQの機能にアクセスするために必要です。\n\n```go\nimport (\n\t\"github.com/aws/aws-sdk-go-v2/config\"\n\t\"github.com/vvatanabe/dynamomq\"\n)\n```\n\n次のコードブロックでDynamoMQクライアントを初期化します。AWSの設定を読み込み、その設定を使って新しいDynamoMQクライアントを作成します。ジェネリクスで指定している'ExampleData'を必要に応じて独自のデータ構造に置き換えてください。\n\n```go\nctx := context.Background()\ncfg, err := config.LoadDefaultConfig(ctx)\nif err != nil {\n  panic(\"failed to load aws config\")\n}\nclient, err := dynamomq.NewFromConfig[ExampleData](cfg)\nif err != nil {\n  panic(\"AWS session could not be established!\")\n}\n```\n\nDynamoMQで使用するデータ構造を定義します。'ExampleData'はDynamoDBのデータを表すために使用される構造体です。\n\n```go\ntype ExampleData struct {\n\tData1 string `dynamodbav:\"data_1\"`\n\tData2 string `dynamodbav:\"data_2\"`\n\tData3 string `dynamodbav:\"data_3\"`\n}\n```\n\n### DynamoMQプロデューサーの作成\n\n次のスニペットでは、'ExampleData'型のDynamoMQプロデューサーを作成し、事前に定義されたデータを持つメッセージをキューに送信します。\n\n```go\nproducer := dynamomq.NewProducer[ExampleData](client)\n_, err = producer.Produce(ctx, \u0026dynamomq.ProduceInput[ExampleData]{\n  Data: ExampleData{\n    Data1: \"foo\",\n    Data2: \"bar\",\n    Data3: \"baz\",\n  },\n})\nif err != nil {\n  panic(\"failed to produce message\")\n}\n```\n\n### DynamoMQコンシューマーの作成\n\nメッセージを消費するために、'ExampleData'のDynamoMQコンシューマーをインスタンス化し、新しいゴルーチンで起動します。コンシューマーは、中断シグナルを受け取るまでメッセージを処理し続けます。以下の例には、コンシューマーのグレースフルシャットダウンのロジックが含まれています。\n\n```go\nconsumer := dynamomq.NewConsumer[ExampleData](client, \u0026Counter[ExampleData]{})\ngo func() {\n  err = consumer.StartConsuming()\n  if err != nil {\n    fmt.Println(err)\n  }\n}()\n\ndone := make(chan os.Signal, 1)\nsignal.Notify(done, os.Interrupt, syscall.SIGTERM)\n\n\u003c-done\n\nctx, cancel := context.WithTimeout(context.Background(), time.Minute)\ndefer cancel()\n\nif err := consumer.Shutdown(ctx); err != nil {\n  fmt.Println(\"failed to consumer shutdown:\", err)\n}\n```\n\n以下に、消費されたメッセージを処理するための'Counter'型を定義します。メッセージが処理されるたびにカウンターが増え、メッセージの詳細が表示されます。\n\n```go\ntype Counter[T any] struct {\n\tValue int\n}\n\nfunc (c *Counter[T]) Process(msg *dynamomq.Message[T]) error {\n\tc.Value++\n\tfmt.Printf(\"value: %d, message: %v\\n\", c.Value, msg)\n\treturn nil\n}\n```\n\n## DynamoMQの設計について\n\nDynamoMQの内部的な設計について説明します。\n\n### メッセージの属性とテーブル定義\n\n以下はDynamoMQがメッセージキューを実現するためのテーブル定義を示した図です。\n\n| Key   | Attributes         | Type   | Example Value                       |\n|-------|--------------------|--------|-------------------------------------|\n| PK    | id                 | string | A-101                               |\n|       | data               | any    | any                                 |\n|       | receive_count      | number | 1                                   |\n| GSIPK | queue_type         | string | STANDARD or DLQ                     |\n|       | version            | number | 1                                   |\n|       | created_at         | string | 2006-01-02T15:04:05.999999999Z07:00 |\n|       | updated_at         | string | 2006-01-02T15:04:05.999999999Z07:00 |\n| GSISK | sent_at            | string | 2006-01-02T15:04:05.999999999Z07:00 |\n|       | received_at        | string | 2006-01-02T15:04:05.999999999Z07:00 |\n|       | invisible_until_at | string | 2006-01-02T15:04:05.999999999Z07:00 |\n\nこのテーブル定義に基づき、各属性とグローバルセカンダリインデックス（以下、GSI）について解説します。\n\n#### id（パーティションキー）\n\nメッセージの一意な識別子で、DynamoDBのパーティションキーとして機能します。これによりDynamoDB内のデータの分散と効率的なアクセスが可能になります。DynamoMQのパブリッシャーを使用すると、デフォルトでUUIDが自動生成されます。ユーザーは独自のIDを指定することも可能です。\n\n#### data  \n\nメッセージに含まれるデータの内容です。DynamoDBがサポートする任意の形式で保存できます。\n\n参考:\n- [DynamoDB Data Types](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.DataTypes.html)\n- [DynamoDB Item sizes and formats](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/CapacityUnitCalculations.html)\n\n#### receive_count\n\nメッセージが受信された回数を表します。この数値は再試行やデッドレターキューへの移動を管理する際に使用されます。\n\n#### queue_type（GSIのプライマリーキー）\n\nメッセージが保存されているキューのタイプを示します。スタンダードキュー（STANDARD）かデッドレターキュー（DLQ）かを区別します。\n\n#### version\n\nメッセージのバージョン番号です。メッセージが更新されるたびにこの数値は増加し、楽観的排他制御を実現します。\n\n#### created_at  \n\nメッセージが作成された日時です。ISO 8601形式で記録されます。\n\n#### updated_at  \n\nメッセージが最後に更新された日時です。ISO 8601形式で記録されます。\n\n#### sent_at (Sort Key for GSI)\n\nメッセージがキューに送信された日時です。ISO 8601形式で記録されます。\n\n#### received_at\n\nメッセージが受信された日時です。ISO 8601形式で記録されます。\n\n#### invisible_until_at\n\nメッセージがキュー内で次に可視化される日時です。この時間が過ぎると、メッセージは再度受信可能になります。\n\n#### グローバルセカンダリインデックス（GSI）\n\nキューに追加された順序でメッセージを受信するために、`queue_type`をパーティションキーとし、`sent_at`をソートキーとするGSIが設定されています。\n\n### メッセージの状態遷移\n\n以下の状態遷移図は、DynamoMQにおけるメッセージのライフサイクルと、それが取りうる状態の遷移を示しています。図には、スタンダードキュー（`queue_type=STANDARD`）とデッドレターキュー（`queue_type=DLQ`）でのメッセージの処理方法が示されています。\n\n![State Machine](https://cacoo.com/diagrams/DjoA2pSKnhCghTYM-9383C.png) \n\nまた、以下の図ではメッセージの属性が状態遷移に伴いどのように変化するかを示しています。赤色で示された属性は状態遷移によって更新されます。\n\n![Data Transition](https://cacoo.com/diagrams/DjoA2pSKnhCghTYM-DCE15.png)\n\nこれらの図に示されたプロセスをステップバイステップで説明します。\n\n#### スタンダードキューの状態遷移の説明\n\n1. **メッセージの送信**\n   - プロデューサーは、`SendMessage()`関数を使用してスタンダードキューにメッセージを送信します。\n   - 送信されたメッセージは「READY」状態になり、これはメッセージが受信可能な状態を意味します。\n   - このメッセージには一意のIDが割り当てられ、`data`フィールドには処理されるべきデータが含まれます。\n   - メッセージの`queue_type`属性は`STANDARD`に設定され、バージョンは初期状態で `1` になります。\n   - `created_at`、`updated_at`、`sent_at`のタイムスタンプが記録されます。\n\n2. **メッセージの受信**\n   - コンシューマーは、`ReceiveMessage()`関数を利用してメッセージを受信し、処理を開始します。\n   - メッセージは「PROCESSING」状態に移行し、この期間中は他のコンシューマーからは見えなくなり、受信されなくなります。\n   - メッセージの`receive_count`と`version`はそれぞれ受信の度にインクリメントされます。\n   - `updated_at`、`received_at`のタイムスタンプが更新され、`invisible_until_at`が新しい日時で設定されます。\n\n3. **処理の成功**\n   - 処理が成功した場合、コンシューマーは`DeleteMessage()`関数を使用してメッセージをキューから削除します。\n\n4. **処理の失敗**\n   - 処理に失敗した場合、特にリトライが必要な場合は、`ChangeMessageVisibility()`を使用してメッセージの`invisible_until_at`属性を更新し、後で再処理できるようにします。\n   - `invisible_until_at`の設定された日時が過ぎれば、メッセージは再び「READY」状態に戻り、再度受信が可能になります。\n\n#### デッドレターキューの状態遷移の説明\n\n1. **DLQへの移動**\n   - メッセージの処理が最大再配信回数を超えて失敗すると、`MoveMessageToDLQ()`関数によってメッセージはデッドレターキュー（DLQ）に移動されます。\n   - この時、メッセージの`queue_type`は`DLQ`に変更され、`receive_count`は`0`にリセットされます。\n   - DLQに移動されたメッセージは、再び「READY」状態に戻ります。\n\n2. **メッセージの受信**\n   - DLQ内で、メッセージは再び`ReceiveMessage()`によって受信され、`PROCESSING`状態に遷移します。\n   - この期間中、メッセージは他のコンシューマーからは見えなくなります。\n\n3. **処理の成功**\n   - メッセージが正常に処理されると、`DeleteMessage()`によってDLQから削除されます。\n\n4. **スタンダードキューへの移動**\n   - `RedriveMessage()`を使用してメッセージを元のスタンダードキューに戻すことも可能です。\n   - この操作により、`queue_type`は再び`STANDARD`に設定され、メッセージは「READY」状態に戻ります。\n\n## まとめ\n\nDynamoMQは、DynamoDBの特性を生かし、高いスケーラビリティ、信頼性、およびコスト効率を実現するメッセージキューのライブラリです。特に、メッセージの順序変更や属性を動的に編集できる点は、アプリケーションの要求を柔軟に対応することを可能にします。\n\n既存のソリューションと比較して、DynamoMQは開発者にとって管理が容易でありながら、Amazon SQSのようなフルマネージドサービスの信頼性を提供します。また、複数のゴルーチンによる並列実行処理や、デッドレターキュー、FIFO順序の保証など、メッセージキューが提供すべき主要な機能を網羅しています。\n\n## 謝辞\n\nDynamoMQの開発にあたり参考とさせていただいたAWSの公式ブログ「[Implementing priority queueing with Amazon DynamoDB](https://aws.amazon.com/blogs/database/implementing-priority-queueing-with-amazon-dynamodb/)」に深く感謝申し上げます。このブログでは、Amazon DynamoDBを使用した優先度付きキューイングの実装方法が詳細に解説されており、その知識がDynamoMQの構築に非常に役立ちました。\n\n## 著者\n\n* **[vvatanabe](https://github.com/vvatanabe/)** - *主要な貢献者*\n\n## ライセンス\n\nこのプロジェクトはMITライセンスです。詳細なライセンス情報については、リポジトリに含まれる[LICENSE](LICENSE)ファイルを参照してください。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvvatanabe%2Fdynamomq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvvatanabe%2Fdynamomq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvvatanabe%2Fdynamomq/lists"}