feat: MySQL 백업 실패 알림 내부 전용 API 구현

src/main/java/com/example/solidconnection/alarm/config/DbBackupAlarmProperties.java

@@ -0,0 +1,21 @@
+package com.example.solidconnection.alarm.config;
+
+import jakarta.validation.constraints.NotBlank;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.validation.annotation.Validated;
+
+/*
+ * - webhookUrl 이 없으면 알림을 보낼 수 없으므로 기동 시점에 검증한다.
+ * - mentionRoleId 는 선택 값이며, 없으면 멘션 없이 알림만 보낸다.
+ * */
+@Validated
+@ConfigurationProperties(prefix = "discord.db-backup-fail-alarm")
+public record DbBackupAlarmProperties(
+
+        @NotBlank
+        String webhookUrl,
+
+        String mentionRoleId
+) {
+
+}

src/main/java/com/example/solidconnection/alarm/config/InternalAlarmAuthProperties.java

@@ -0,0 +1,10 @@
+package com.example.solidconnection.alarm.config;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+@ConfigurationProperties(prefix = "internal-alarm")
+public record InternalAlarmAuthProperties(
+        String token
+) {
+
+}

src/main/java/com/example/solidconnection/alarm/controller/DbBackupAlarmController.java

@@ -0,0 +1,32 @@
+package com.example.solidconnection.alarm.controller;
+
+import com.example.solidconnection.alarm.dto.DbBackupAlarmRequest;
+import com.example.solidconnection.alarm.service.DbBackupAlarmService;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/internal/alarms")
+@RequiredArgsConstructor
+public class DbBackupAlarmController {
+
+    private static final String INTERNAL_ALARM_TOKEN_HEADER = "X-Internal-Alarm-Token";
+
+    private final DbBackupAlarmService dbBackupAlarmService;
+
+    // DB EC2 의 백업 실패 이벤트를 받아 Discord 로 알리는 내부 전용 api
+    @PostMapping("/db-backup")
+    public ResponseEntity<Void> alarmBackupFailure(
+            @RequestHeader(value = INTERNAL_ALARM_TOKEN_HEADER, required = false) String token,
+            @Valid @RequestBody DbBackupAlarmRequest dbBackupAlarmRequest
+    ) {
+        dbBackupAlarmService.alarmBackupFailure(token, dbBackupAlarmRequest);
+        return ResponseEntity.accepted().build();
+    }
+}

src/main/java/com/example/solidconnection/alarm/domain/DbBackupAlarmSeverity.java

@@ -0,0 +1,17 @@
+package com.example.solidconnection.alarm.domain;
+
+import lombok.Getter;
+
+@Getter
+public enum DbBackupAlarmSeverity {
+
+    WARNING("경고"),
+    CRITICAL("심각"),
+    ;
+
+    private final String displayName;
+
+    DbBackupAlarmSeverity(String displayName) {
+        this.displayName = displayName;
+    }
+}

src/main/java/com/example/solidconnection/alarm/domain/DbBackupAlarmType.java

@@ -0,0 +1,25 @@
+package com.example.solidconnection.alarm.domain;
+
+import lombok.Getter;
+
+/*
+ * - 심각도는 호출자가 임의로 낮출 수 없도록 요청 값이 아니라 유형에서 결정한다.
+ * - 지연은 아직 복구 여지가 있어 경고로 두고, 기준점이나 복구 체인이 깨지는 경우는 심각으로 둔다.
+ * */
+@Getter
+public enum DbBackupAlarmType {
+
+    DUMP_FAILED("전체 덤프 실패", DbBackupAlarmSeverity.CRITICAL),
+    BINLOG_UPLOAD_FAILED("바이너리 로그 업로드 실패", DbBackupAlarmSeverity.CRITICAL),
+    BINLOG_GAP_DETECTED("바이너리 로그 누락", DbBackupAlarmSeverity.CRITICAL),
+    BINLOG_UPLOAD_DELAYED("바이너리 로그 업로드 지연", DbBackupAlarmSeverity.WARNING),
+    ;
+
+    private final String displayName;
+    private final DbBackupAlarmSeverity severity;
+
+    DbBackupAlarmType(String displayName, DbBackupAlarmSeverity severity) {
+        this.displayName = displayName;
+        this.severity = severity;
+    }
+}

src/main/java/com/example/solidconnection/alarm/dto/DbBackupAlarmRequest.java

@@ -0,0 +1,25 @@
+package com.example.solidconnection.alarm.dto;
+
+import com.example.solidconnection.alarm.domain.DbBackupAlarmType;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+import java.time.Instant;
+
+public record DbBackupAlarmRequest(
+
+        @NotNull
+        DbBackupAlarmType type,
+
+        @NotBlank
+        @Size(max = 64)
+        String instanceId,
+
+        @NotNull
+        Instant occurredAt,
+
+        @Size(max = 1000)
+        String detail
+) {
+
+}

src/main/java/com/example/solidconnection/alarm/service/DbBackupAlarmService.java

@@ -0,0 +1,222 @@
+package com.example.solidconnection.alarm.service;
+
+import static com.example.solidconnection.common.exception.ErrorCode.DB_BACKUP_ALARM_SEND_FAILED;
+import static com.example.solidconnection.common.exception.ErrorCode.INTERNAL_ALARM_UNAUTHORIZED;
+
+import com.example.solidconnection.alarm.config.DbBackupAlarmProperties;
+import com.example.solidconnection.alarm.config.InternalAlarmAuthProperties;
+import com.example.solidconnection.alarm.dto.DbBackupAlarmRequest;
+import com.example.solidconnection.common.discord.DiscordWebhookSender;
+import com.example.solidconnection.common.exception.CustomException;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.time.Duration;
+import java.util.List;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.data.redis.core.RedisTemplate;
+import org.springframework.data.redis.core.script.RedisScript;
+import org.springframework.stereotype.Service;
+
+/*
+ * - DB EC2 는 private subnet 에 있어 Discord 로 직접 요청할 수 없다. 따라서 백업 실패 이벤트를 전달받아 Discord 로 중계한다.
+ * - 같은 실패가 반복될 때 알림이 쌓이지 않도록 억제 간격을 점점 늘린다.
+ * - 억제 상태는 Redis 에 두고 원자적 연산으로 갱신하므로, 서버가 여러 대여도 한 대만 알림을 보낸다.
+ * */
+@Service
+@Slf4j
+public class DbBackupAlarmService {
+
+    private static final String MUTE_KEY_PREFIX = "db-backup-alarm:mute:";
+    private static final String COUNT_KEY_PREFIX = "db-backup-alarm:count:";
+    private static final Duration COUNT_TTL = Duration.ofHours(12);
+    private static final List<Duration> MUTE_DURATIONS = List.of(
+            Duration.ofMinutes(5),
+            Duration.ofMinutes(15),
+            Duration.ofHours(1),
+            Duration.ofHours(6)
+    );
+    private static final String ROLE_MENTION_FORMAT = "<@&%s>";
+    private static final String EMPTY_DETAIL = "-";
+
+    private final DiscordWebhookSender discordWebhookSender;
+    private final DbBackupAlarmProperties dbBackupAlarmProperties;
+    private final InternalAlarmAuthProperties internalAlarmAuthProperties;
+    private final RedisTemplate<String, String> redisTemplate;
+    private final RedisScript<Long> releaseDbBackupAlarmLuaScript;
+
+    @Value("${spring.profiles.active:}")
+    private String environment;
+
+    public DbBackupAlarmService(
+            DiscordWebhookSender discordWebhookSender,
+            DbBackupAlarmProperties dbBackupAlarmProperties,
+            InternalAlarmAuthProperties internalAlarmAuthProperties,
+            RedisTemplate<String, String> redisTemplate,
+            @Qualifier("releaseDbBackupAlarmScript") RedisScript<Long> releaseDbBackupAlarmLuaScript
+    ) {
+        this.discordWebhookSender = discordWebhookSender;
+        this.dbBackupAlarmProperties = dbBackupAlarmProperties;
+        this.internalAlarmAuthProperties = internalAlarmAuthProperties;
+        this.redisTemplate = redisTemplate;
+        this.releaseDbBackupAlarmLuaScript = releaseDbBackupAlarmLuaScript;
+    }
+
+    public void alarmBackupFailure(String token, DbBackupAlarmRequest request) {
+        validateToken(token);
+
+        String alarmKey = buildAlarmKey(request);
+        String muteKey = MUTE_KEY_PREFIX + alarmKey;
+        String countKey = COUNT_KEY_PREFIX + alarmKey;
+
+        if (!acquireAlarmGate(muteKey)) {
+            return;
+        }
+        long alarmCount = increaseAlarmCount(countKey);
+        Duration muteDuration = resolveMuteDuration(alarmCount);
+        extendAlarmGate(muteKey, muteDuration);
+
+        boolean isSent = discordWebhookSender.send(
+                dbBackupAlarmProperties.webhookUrl(),
+                buildMessage(request, alarmCount, muteDuration),
+                mentionableRoleIds()
+        );
+        if (!isSent) {
+            releaseAlarmGate(muteKey, countKey);
+            throw new CustomException(DB_BACKUP_ALARM_SEND_FAILED);
+        }
+    }
+
+    /*
+     * - 토큰이 설정되지 않은 환경에서는 모든 요청을 거부한다.
+     * - 설정 누락과 토큰 불일치를 같은 응답으로 처리해 내부 상태가 드러나지 않게 한다.
+     * */
+    private void validateToken(String token) {
+        String configuredToken = internalAlarmAuthProperties.token();
+        if (configuredToken == null || configuredToken.isBlank()) {
+            log.error("내부 알림 인증 토큰이 설정되지 않아 요청을 거부했습니다.");
+            throw new CustomException(INTERNAL_ALARM_UNAUTHORIZED);
+        }
+        if (token == null || !MessageDigest.isEqual(
+                token.getBytes(StandardCharsets.UTF_8),
+                configuredToken.getBytes(StandardCharsets.UTF_8))) {
+            throw new CustomException(INTERNAL_ALARM_UNAUTHORIZED);
+        }
+    }
+
+    private String buildAlarmKey(DbBackupAlarmRequest request) {
+        return request.type().name() + ":" + request.instanceId();
+    }
+
+    /*
+     * - setIfAbsent 는 원자적이므로 여러 서버가 동시에 요청받아도 한 대만 통과한다.
+     * - 통과하지 못하면 억제 중이거나 다른 서버가 방금 알림을 보낸 것이므로 전송하지 않는다.
+     * - Redis 를 사용할 수 없을 때는 알림 누락을 막기 위해 통과시킨다.
+     * */
+    private boolean acquireAlarmGate(String muteKey) {
+        try {
+            Boolean isAcquired = redisTemplate.opsForValue()
+                    .setIfAbsent(muteKey, "1", MUTE_DURATIONS.getFirst());
+            return Boolean.TRUE.equals(isAcquired);
+        } catch (Exception e) {
+            log.error("백업 알림 억제 상태를 확인하지 못해 알림을 그대로 전송합니다. key={}", muteKey, e);
+            return true;
+        }
+    }
+
+    /*
+     * - 게이트를 통과한 요청만 카운트하므로 서버가 여러 대여도 연속 발생 횟수가 부풀지 않는다.
+     * */
+    private long increaseAlarmCount(String countKey) {
+        try {
+            Long alarmCount = redisTemplate.opsForValue().increment(countKey);
+            redisTemplate.expire(countKey, COUNT_TTL);
+            if (alarmCount == null) {
+                return 1L;
+            }
+            return alarmCount;
+        } catch (Exception e) {
+            log.error("백업 알림 연속 발생 횟수를 증가하지 못했습니다. key={}", countKey, e);
+            return 1L;
+        }
+    }
+
+    private Duration resolveMuteDuration(long alarmCount) {
+        int index = (int) Math.min(alarmCount, MUTE_DURATIONS.size()) - 1;
+        return MUTE_DURATIONS.get(Math.max(index, 0));
+    }
+
+    /*
+     * - 최초 잠금은 가장 짧은 간격으로 걸어두고, 연속 발생 횟수에 맞는 간격으로 늘린다.
+     * */
+    private void extendAlarmGate(String muteKey, Duration muteDuration) {
+        try {
+            redisTemplate.expire(muteKey, muteDuration);
+        } catch (Exception e) {
+            log.error("백업 알림 억제 간격을 늘리지 못했습니다. key={}", muteKey, e);
+        }
+    }
+
+    private String buildMessage(DbBackupAlarmRequest request, long alarmCount, Duration muteDuration) {
+        return buildRoleMention()
+                + "[%s] [%s] MySQL 백업 알림: %s\n인스턴스: %s\n발생 시각: %s\n연속 발생: %d회 (다음 %s 동안 같은 알림을 보내지 않습니다)\n상세: %s"
+                .formatted(
+                        environment.toUpperCase(),
+                        request.type().getSeverity().getDisplayName(),
+                        request.type().getDisplayName(),
+                        request.instanceId(),
+                        request.occurredAt(),
+                        alarmCount,
+                        formatDuration(muteDuration),
+                        resolveDetail(request.detail())
+                );
+    }
+
+    /*
+     * - 멘션할 역할이 설정되지 않으면 멘션 없이 알림만 보낸다.
+     * */
+    private String buildRoleMention() {
+        String mentionRoleId = dbBackupAlarmProperties.mentionRoleId();
+        if (mentionRoleId == null || mentionRoleId.isBlank()) {
+            return "";
+        }
+        return ROLE_MENTION_FORMAT.formatted(mentionRoleId) + "\n";
+    }
+
+    private String formatDuration(Duration duration) {
+        long hours = duration.toHours();
+        if (hours > 0) {
+            return hours + "시간";
+        }
+        return duration.toMinutes() + "분";
+    }
+
+    private String resolveDetail(String detail) {
+        if (detail == null || detail.isBlank()) {
+            return EMPTY_DETAIL;
+        }
+        return detail;
+    }
+
+    private List<String> mentionableRoleIds() {
+        String mentionRoleId = dbBackupAlarmProperties.mentionRoleId();
+        if (mentionRoleId == null || mentionRoleId.isBlank()) {
+            return List.of();
+        }
+        return List.of(mentionRoleId);
+    }
+
+    /*
+     * - 전송에 실패하면 억제와 횟수를 되돌려 다음 요청이 다시 알림을 시도할 수 있게 한다.
+     * - dump 는 하루 한 번 실행되므로 실패를 그대로 두면 그날의 알림이 사라진다.
+     * - 억제 해제와 횟수 감소를 나누어 실행하면 그 사이에 다른 서버가 증가시킨 횟수를 잘못 줄이므로 lua 로 함께 처리한다.
+     * */
+    private void releaseAlarmGate(String muteKey, String countKey) {
+        try {
+            redisTemplate.execute(releaseDbBackupAlarmLuaScript, List.of(muteKey, countKey));
+        } catch (Exception e) {
+            log.error("백업 알림 억제 상태를 해제하지 못했습니다. key={}", muteKey, e);
+        }
+    }
+}

src/main/java/com/example/solidconnection/common/config/client/RestTemplateConfig.java

@@ -4,16 +4,32 @@
 import org.springframework.boot.web.client.RestTemplateBuilder;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
+import org.springframework.http.client.SimpleClientHttpRequestFactory;
 import org.springframework.web.client.RestTemplate;
 
 @Configuration
 public class RestTemplateConfig {
 
+    private static final Duration TIMEOUT = Duration.ofSeconds(5);
+
     @Bean
     public RestTemplate restTemplate(RestTemplateBuilder restTemplateBuilder) {
         return restTemplateBuilder
-                .setConnectTimeout(Duration.ofSeconds(5))
-                .setReadTimeout(Duration.ofSeconds(5))
+                .connectTimeout(TIMEOUT)
+                .readTimeout(TIMEOUT)
                 .build();
     }
+
+    /*
+     * - Discord webhook url 은 경로에 인증 토큰을 포함한다.
+     * - RestTemplateBuilder 로 만든 RestTemplate 은 observation 이 적용되어 요청 url 이 메트릭 태그로 남을 수 있으므로,
+     *   webhook 전송에는 observation 이 붙지 않는 별도 인스턴스를 사용한다.
+     * */
+    @Bean
+    public RestTemplate discordWebhookRestTemplate() {
+        SimpleClientHttpRequestFactory requestFactory = new SimpleClientHttpRequestFactory();
+        requestFactory.setConnectTimeout((int) TIMEOUT.toMillis());
+        requestFactory.setReadTimeout((int) TIMEOUT.toMillis());
+        return new RestTemplate(requestFactory);
+    }
 }