document sns-sqs-ses

Author: donaldte

18-projects/1-java-notification-app-ses-cf/docker-compose.yml

@@ -0,0 +1,25 @@
+version: "3.8"
+
+services:
+  localstack:
+    container_name: "${LOCALSTACK_DOCKER_NAME-localstack-main}"
+    image: localstack/localstack-pro
+    ports:
+      - "127.0.0.1:4510-4559:4510-4559"  # external service port range
+      - "127.0.0.1:4566:4566"            # LocalStack Edge Proxy
+    environment:
+      - DEBUG=1
+      - LAMBDA_EXECUTOR=${LAMBDA_EXECUTOR-}
+      - HOST_TMP_FOLDER=${TMPDIR:-/tmp/}localstack
+      - DOCKER_HOST=unix:///var/run/docker.sock
+      - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN-}
+      - SMTP_HOST=smtp:1025
+    volumes:
+      - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"
+      - "/var/run/docker.sock:/var/run/docker.sock"
+
+  smtp:
+    image: mailhog/mailhog
+    ports:
+      - "1025"
+      - "8025:8025"

18-projects/1-java-notification-app-ses-cf/readme.md

@@ -0,0 +1,199 @@
+
+# **AWS Messaging : Spring Boot avec LocalStack**
+
+Ce projet d’application Spring Boot montre comment :
+
+* Déployer une infrastructure CloudFormation sur LocalStack
+* Configurer des abonnements SNS → SQS via CloudFormation
+* Recevoir des messages SQS avec le SDK Java AWS
+* Envoyer des emails avec AWS SES via le SDK Java AWS
+
+---
+
+# ✅ **Prérequis**
+
+* **Java 11+**
+* **Maven 3+**
+* **LocalStack** (simulateur local des services AWS)
+* **awslocal** (wrapper AWS CLI pour LocalStack)
+
+---
+
+# 🚀 **Comment exécuter le projet**
+
+## 1️⃣ **Construire l’application**
+
+Il s’agit d’une application Spring Boot classique, compilée avec :
+
+```bash
+mvn clean install
+```
+
+---
+
+## 2️⃣ **Lancer l’infrastructure sur LocalStack**
+
+L’infrastructure est définie dans le fichier CloudFormation :
+
+```
+src/main/resources/email-infra.yml
+```
+
+### ➤ Démarrer LocalStack + le serveur SMTP
+
+```bash
+LOCALSTACK_AUTH_TOKEN=<your-api-key> docker-compose up -d
+```
+
+### ➤ Déployer la stack CloudFormation
+
+```bash
+awslocal cloudformation deploy \
+    --template-file src/main/resources/email-infra.yml \
+    --stack-name email-infra
+```
+
+---
+
+## 3️⃣ **Démarrer l’application Spring Boot**
+
+Vous devez définir deux variables d’environnement :
+
+```bash
+AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test mvn spring-boot:run
+```
+
+(Ces valeurs sont fictives car LocalStack n’a pas besoin de vraies clés.)
+
+---
+
+## 4️⃣ **Tester l’application**
+
+### ✔ Vérifier l’email expéditeur
+
+```bash
+awslocal ses verify-email-identity --email-address no-reply@localstack.cloud
+```
+
+### ✔ Envoyer un message SNS
+
+```bash
+awslocal sns publish \
+    --topic arn:aws:sns:us-east-1:000000000000:email-notifications \
+    --message '{"subject":"hello", "address": "alice@example.com", "body": "hello world"}'
+```
+
+### ✔ Vérifier les messages dans la file SQS via l’endpoint `/list`
+
+```bash
+curl -s localhost:8080/list | jq .
+```
+
+### ✔ Traiter les messages et envoyer les emails
+
+```bash
+curl -s localhost:8080/process
+```
+
+### ✔ Vérifier les emails envoyés
+
+👉 Via MailHog : [http://localhost:8025/](http://localhost:8025/)
+👉 Via l’endpoint interne SES de LocalStack :
+
+```bash
+curl -s localhost:4566/_localstack/ses | jq .
+```
+
+---
+
+# 🧠 **Explication détaillée des services AWS et de leurs rôles**
+
+
+# 🟦 **1. AWS CloudFormation — Déploiement automatique de l’infrastructure**
+
+CloudFormation permet de **définir et déployer l'architecture AWS sous forme de code (IaC)**.
+
+Dans ce projet, CloudFormation crée automatiquement :
+
+* un **topic SNS**
+* une **file SQS**
+* un **abonnement SNS → SQS**
+* les politiques d’accès nécessaires
+
+**Rôle :**
+➡ Automatiser toute l’infrastructure sans cliquer dans AWS.
+➡ Résultat : déploiement reproductible, versionné et contrôlé.
+
+---
+
+# 🟧 **2. AWS SNS (Simple Notification Service) — Service de publication/subscription**
+
+SNS est un service de **messagerie pub/sub**.
+
+Dans ce projet :
+
+* l’application (ou un service externe) **publie un message dans le topic SNS**
+* SNS redirige le message vers la file SQS qui y est abonnée
+
+**Rôle :**
+➡ Servir de **point d’entrée** des notifications.
+➡ Distribuer les messages à un ou plusieurs abonnés.
+
+---
+
+# 🟩 **3. AWS SQS (Simple Queue Service) — File de messages**
+
+SQS est une file utilisée pour :
+
+* découpler les systèmes
+* absorber une grande charge de messages
+* garantir la livraison même si les services consommateurs sont offline
+
+Dans ce projet :
+
+* SQS reçoit les messages envoyés depuis le topic SNS
+* L’application Spring Boot **lit SQS grâce au SDK AWS**
+* Chaque message contient :
+
+  * un sujet
+  * une adresse email du destinataire
+  * un contenu
+
+**Rôle :**
+➡ Assurer une messagerie fiable entre SNS et Spring Boot.
+
+---
+
+# 🟪 **4. AWS SES (Simple Email Service) — Envoi d’emails**
+
+SES est un service pour envoyer des emails transactionnels.
+
+Dans ce projet :
+
+* Après avoir lu les messages dans SQS
+* L’application Spring Boot utilise **AWS SES** pour envoyer un email au destinataire
+* L'email est simulé par LocalStack (et visualisable via MailHog)
+
+**Rôle :**
+➡ Convertir un message métier en un **email réel** envoyé à l’utilisateur final.
+
+---
+
+# 🟫 **5. LocalStack — Simulateur AWS sur votre machine**
+
+LocalStack émule de nombreux services AWS :
+
+* SNS
+* SQS
+* SES
+* CloudFormation
+* Lambda
+* etc.
+
+Sans coût AWS, sans connexion Internet.
+
+**Rôle :**
+➡ Permettre un développement 100 % local
+➡ Tester une architecture AWS complète sans payer
+
+

18-projects/1-java-notification-app-ses-cf/src/main/java/com/example/AwsConfiguration.java

@@ -15,6 +15,8 @@
 public class AwsConfiguration {
 
     private static final String ENDPOINT_URL = "http://localhost:4566";
+
+
     private static final Region DEFAULT_REGION = Region.US_EAST_1;
 
     @Bean
@@ -23,6 +25,7 @@ public SqsClient sqsClient() {
                 .region(DEFAULT_REGION)
                 .credentialsProvider(EnvironmentVariableCredentialsProvider.create())
                 .applyMutation(builder -> {
+                    // TODO: conditional local-dev injection
                     builder.endpointOverride(URI.create(ENDPOINT_URL));
                 })
                 .build();
@@ -34,6 +37,7 @@ public SesClient sesClient() {
                 .region(DEFAULT_REGION)
                 .credentialsProvider(EnvironmentVariableCredentialsProvider.create())
                 .applyMutation(builder -> {
+                    // TODO: conditional local-dev injection
                     builder.endpointOverride(URI.create(ENDPOINT_URL));
                 })
                 .build();
@@ -43,6 +47,7 @@ public SesClient sesClient() {
     @Autowired
     public String notificationQueueUrl(SqsClient sqsClient) {
         return sqsClient.getQueueUrl(builder -> {
+            // TODO: could get QueueUrl from stack output properties
             builder.queueName("email-notification-queue");
         }).queueUrl();
     }

18-projects/1-java-notification-app-ses-cf/src/main/java/com/example/MessageApplication.java

@@ -0,0 +1,13 @@
+package com.example;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+public class MessageApplication {
+
+    public static void main(String[] args) {
+        SpringApplication.run(MessageApplication.class, args);
+    }
+
+}

18-projects/1-java-notification-app-ses-cf/src/main/java/com/example/NotificationController.java

@@ -0,0 +1,45 @@
+package com.example;
+
+import java.util.HashMap;
+import java.util.List;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Controller;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestMethod;
+import org.springframework.web.bind.annotation.ResponseBody;
+
+
+@Controller
+public class NotificationController {
+
+    @Autowired
+    ReceiveSendNotifications msgService;
+
+    // send emails for all parsable notifications
+    @RequestMapping(value = "/process", method = RequestMethod.GET)
+    @ResponseBody
+    List<String> processNotifications(HttpServletRequest request, HttpServletResponse response) {
+        return msgService.processNotifications();
+    }
+
+
+    //  Lists all message bodies
+    @RequestMapping(value = "/list", method = RequestMethod.GET)
+    @ResponseBody
+    List<HashMap<String, String>> listMessages(HttpServletRequest request, HttpServletResponse response) {
+        return msgService.listMessages();
+    }
+
+
+    //  Purge the message queue
+    @RequestMapping(value = "/purge", method = RequestMethod.GET)
+    @ResponseBody
+    void purgeQueue(HttpServletRequest request, HttpServletResponse response) {
+        msgService.purgeQueue();
+    }
+
+}